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CHAPTER 4 


INTRODUCTION 


Beneath Apple ProDOS is intended to serve as a companion to 
the manuals provided by Apple Computer, Inc. for ProDOS, 
providing additional information for the advanced programmer or 
for the novice Apple user who wants to know more about the 
structure of disks. It is not the intent of this manual to replace the 
documentation provided by Apple. Although, for the sake of 
continuity, some of the material covered in the Apple manuals is 
also covered here, it will be assumed that the reader is reasonably 
familiar with the contents of Apple’s ProDOS User’s Manual and 
BASIC Programming With ProDOS. Since all chapters presented 
here may not be of use to each Apple owner, each has been written 
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to stand on its own. Readers of our earlier book, Beneath A pple 
DOS, will notice that we have retained the basic organization of 
that book in an attempt to help them familiarize themselves with 
Beneath Apple ProDOS more quickly. 

The information presented here is a result of intensive 
disassembly and annotation of various versions of ProDOS by the 
authors. It also uses as a reference various application notes and 
preliminary documentation from Apple. Although no guarantee 
can be made concerning the accuracy of the information presented 
here, all of thc .naterial included in Beneath Apple ProDOS has 
been thoroughly researched and tested. 

There were several reasons for writing Beneath Apple ProDOS: 


@ To show how to access ProDOS and/or the Disk II drive 
directly from machine language. 

@ To help you fix damaged disks. 

@ Tocorrect errors and omissions in the Apple documentation. 

@ To allow you to customize ProDOS to fit your needs. 

®@ To provide complete information on diskette formatting. 

@ To document the internal logic of ProDOS. 

®@ To present a critical, non-Apple perspective of ProDOS. 

®@ To provide more examples of ProDOS programming. 

@ To help you to learn about how an operating system works. 


When Apple introduced ProDOS Version 1.0.1 in January 1984, 
three manuals were available: the ProDOS User’s Manual 
documents the use of ProDOS utilities; the BASIC Programming 
With ProDOS manual describes the command language supported 
by the BASIC Interpreter and how to write BASIC programs 
which access the disk; and the ProDOS Technical Reference 
Manual (for the Apple II family) documents the assembly language 
interfaces to ProDOS. It should be stated that this technical 
referc: osm onal represents the best internal documentation 
Appie as c.er provided to users of one of their operating systems. 
Unfortunately, the ProDOS Technical Reference Manual 
documents a prerelease version of ProDOS, and is not entirely 
accurate for the current release at the time of this writing. In 
addition, many sections require further explanation before the 
interfaces they describe can be used at all. For example, the 
discussion of how one adds a command to the BASIC Interpreter 
omits several vital pieces of information which are documented 
fully in Beneath Apple ProDOS. In addition, none of the Apple 
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documentation addresses diskette formatting or direct access of 
the Disk II family of controllers from assembly language. Beneath 
Apple ProDOS was written in an attempt to improve upon the 
documentation base established by Apple. Most of the topics 
covered by Apple’s technical manual are covered here also, but 
they are explained in a different and, we hope, clearer way, based 
upon a programmer’s understanding of the code in the ProDOS 
Kernel and the BASIC Interpreter. We have also added 
substantial information on diskette formatting and repair, the 
internal logic and structure of ProDOS, and customizing 
techniques, as well as providing several example programs and 
quick reference materials. 

In addition to the ProDOS specific information provided, many 
of the discussions also apply to other operating systems in the 
Apple II and Apple III family of machines. For example, disk 
formatting at the track and sector level is for the most part the 
same. Also, the format of a ProDOS volume is nearly identical to 
that of an Apple ITISOS volume. 

For those readers who would like to have a detailed description 
of every bit of code in the current version of ProDOS, a supplement 
to this book is available and can be ordered directly from Quality 
Software. Please see Chapter 8 for details. 


CHAPTER 2 


TO BUILD A BETTER DOS 


From June 1978 to January 1984, the primary disk operating 
system for the Apple II family was Apple DOS. Throughout 
its first six years of existence, DOS has gone through a number of 
changes, culminating in its final version, DOS 3.3. DOS was 
originally designed primarily to support the BASIC programmer, 
but has since been adopted by assembly language programmers 
and by the majority of Apple users for a variety of applications. 


THE DEFICIENCIES OF DOS 


Although it is a flexible and easy to use operating system, DOS 
suffers from many weaknesses. Among these are: 


@ DOS isslow. Since each byte read from the disk is copied 
between memory buffers up to three times, a large portion of 
the actual overhead in reading data from the disk is in 
processor manipulation after the data has been read. To 
circumvent this, several “fast DOS” packages have been 
marketed by third parties which heavily modify DOS to 
prevent multiple buffering under certain circumstances. 


@ DOS is device dependent. When DOS was developed, the only 
mass storage device for the Apple was the Disk II diskette 
drive. Now that diskette drives with increased capacity and 
hard disks are available, a more device independent file 
organization is needed. DOS is limited in the number of files 
which can be stored on a diskette as well as their maximum 
size. These are significant drawbacks when a hard disk with 
five million bytes or more is used. 
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Over the years, new hardware has been introduced by Apple 
and other manufacturers which DOS does not intrinsically 
support. The Apple Ile with its 80-column card and the 
Thunderclock are examples. 


DOS is difficult to customize. There are few external “hooks” 
provided to allow system programmers the opportunity to 
personalize the operating system to special applications. For 
example, a new command cannot be added to DOS without 
version dependent patches. 


DOS file structures and system calls are incompatible with 
other operating systems. Each operating system Apple has 
announced in the past has had its own way of organizing data 
on a diskette. There is no compatibility between DOS, SOS and 
the Apple Pascal system. This means that special utilities must 
be written to move data between these systems and that 
applications developed in one environment will not run 
without major modifications under any other system. 


DOS does not provide a consistent mechanism for supporting 
multiple peripherals which can generate hardware interrupts. 
In the past, various manufacturers have implemented 
interrupt handlers on their own, often resulting in 
incompatibilities between their devices. 


DOS provides little standardization of memory use and of 
operating system interfaces. Most “interesting” locations 
within DOS are internalized and therefore not officially 
available to the programmer. Also, since there is no standard 
way to set aside portions of memory for specific applications, it 
is difficult to put a program in a “safe” place so that it may co- 
reside with another application. 


Although DOS allows most of its commands to be executed 
from within a BASIC program, additional function is needed. 
Under DOS, there is no way to conveniently read a file 
directory from a BASIC program, or to save and restore 
Applesoft’s variables, for example. Likewise, the 
implementation of program CHAINing is not integrated into 
DOS. 
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@ Additional functions under DOS which would also be desirable 
(to name only a few) are: a display of the amount of freespace 
left on a diskette; a way to show the address and length 
parameters stored with a binary file; and a way to create 
unbootable data disks to increase storage space for user files. 


ENTER ProDOS 


In January 1984, Apple introduced a new disk operating system 
for its Apple II family of computers. ProDOS is intended to replace 
DOS 3.3 as the standard Apple II operating system, and it is now 
being shipped with all new Disk II drives instead of DOS. 
Although, on the surface, ProDOS is very similar in appearance to 
DOS 3.3, it represents a major redesign and is a new and separate 
system. From the beginning, ProDOS addresses all of DOS’s 
weaknesses mentioned above: 


@ ProDOS is up to eight times faster than DOS in disk access. A 
new “direct read” mode has been implemented which allows 
multisector reads to be performed directly from the disk to the 
programmer’s buffer without multiple buffering within 
ProDOS itself. When performing direct reads, ProDOS can 
transfer data from the diskette at a rate of eight kilobytes per 
second (at best, DOS can read one kilobyte per second). Even 
when reading small amounts of data from the disk, ProDOS 
does less multiple buffering than does DOS. 
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ProDOS provides a device independent interface to “foreign’ 
mass storage devices. The concept of a hierarchically 
organized disk “volume” was created to allow for large 
capacity devices, and vectors are provided to allow device 
drivers for non-standard disks to be integrated into ProDOS. 
Directories may be dynamically expanded to unlimited size to 
allow for large numbers of files, and an individual file may 
now occupy up to 16 million bytes of space on a volume. The 
largest volume which can be supported is 32 million bytes. 


Device driver support has also been provided for 
calendar/clock peripherals, allowing time and date stamping 
of files, and support for the Apple Ile and IIc 80-column 
hardware is a part of ProDOS. 


Learning from its mistakes with DOS, Apple has externalized 
as many ProDOS functions as possible through well defined 
system calls. In addition to standard file management system 
calls, interfaces are provided to support user written 
commands to the BASIC Interpreter, and to invoke a ProDOS 
command from within an assembly language program. 


The ProDOS file and volume structure is nearly identical to 
that of the Apple III SOS operating system. There are even 
strong similarities between ProDOS system calls and those on 
Apple’s Macintosh! A ProDOS volume may be accessed from 
SOS directly without the need for a special utility program. 
ProDOS system calls are a large subset of those offered under 
SOS, and applications may be developed which will easily port 
between the two operating systems. 


ProDOS defines a protocol which interrupting devices may use 
to coexist harmoniously in the same machine. Up to four 
interrupt drivers may be installed in ProDOS, and each device 
need not know that the others exist. 


Most system locations of general interest have been placed in 
externally accessible areas of memory called global pages. 
Through a global page, a user written program can obtain the 
current ProDOS version number, the most recent values 
entered on a ProDOS command line, or the configuration of the 
current hardware including the machine type, memory size, 
and contents of the peripheral card slots. In addition, a 
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voluntary system has been provided to “fence off” portions of 
memory for special uses by marking a memory bit map in the 
system global page. 


New support has been provided under ProDOS for BASIC 
programmers. A BASIC program can now read a directory 
file, make a “snapshot” of its variables on disk and later restore 
them, and chain between programs, preserving the variables. 


The CATALOG command under ProDOS displays the address 
and length values of binary files as well as the space 
remaining on a disk volume. 


MORE ProDOS ADVANTAGES 


In addition to addressing needs which grew out of DOS, Apple 


has also come up with other enhancements with ProDOS: 


A new “smart” RUN command (“~”) has been added which will 
automatically perform the function of a RUN, EXEC or 


BRUN as appropriate depending upon the type of file being 
RUN. 


The assembly language interface has been expanded to include 
obtaining and updating statistical information about a file, 
moving the end of file mark in a file, allowing line-at-a-time 
reads versus byte stream reads, determining the names of 
diskettes mounted in online drives, and creating new files or 
directories. In addition, entry points are included to allow 
applications to pass control from program to program and to 
allocate memory. 


The language independent, file management portion of 
ProDOS (the Kernel), is a separate unit from the BASIC 
support routines. Applications may be written which reclaim 
the memory normally occupied by BASIC support routines. 


All ProDOS utilities are menu oriented with enhanced user 
interfaces. 


Owners of the Extended 80-column card in an Apple Ile have 
access to a 64K “RAM/electronic disk drive” under ProDOS. 
Data stored there may be accessed almost instantaneously 
allowing much more efficient loading and storing of programs 
and data. 
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Applesoft string “garbage collection” has been rewritten 
under ProDOS, and is now many times faster and more 
efficient. 


Files may be restricted or “locked” by type of access. Read only 
files may be established, or files which may be written but not 
destroyed, for example. 


The binary save (BSAVE) command has been enhanced under 
ProDOS. BSAVEs into existing binary files whose A and/or L 
keywords are omitted will use the current values of the target 
file. Also, other file types besides BIN files may be BLOADed 
and BSAVE4d, allowing direct modification at a byte-by-byte 
level. (For example, one can BLOAD a text file and examine it 
in memory, making modifications to the hex image.) 


The record length of a random access text file is now stored 
with the file, allowing subsequent BASIC programs to access 
it without knowing its record length. 


Data disk volumes may now be created which do not contain an 
image of the operating system. ProDOS makes more efficient 
use of the disk, resulting in slightly more user storage for files. 
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@ More information about a file is stored in the directory entry 
under ProDOS than under DOS. The length of a binary or 
Applesoft file, for example, is stored in the directory, not in the 
file itself. 


@ The manner in which the ProDOS BASIC Interpreter 
intercepts a BASIC program’s command lines has been 
improved and is more reliable. It is now very difficult to 
“disconnect” ProDOS as could occur under DOS. 


@ More file types (256) are available under ProDOS. Some are 
“user definable.” 


WHAT YOU GIVE UP WITH ProDOS 


ProDOS is not for everyone, however. There are a number of 
disadvantages to moving from DOS to ProDOS: 


@ Most assembly language programs which ran under DOS will 
have to be rewritten for ProDOS. The file management 
interfaces are completely different, and the “PRINT 
control-D” mechanism which worked from assembly language 
under DOS no longer works under ProDOS. This means that 
most commercial applications, such as word processors, 
compilers, and spreadsheets, will not be available for ProDOS 
until they are converted. This state of affairs will change, 
however, since ProDOS is now the “official” operating system 
for Apple II computers. 


@ Apple’s older version of BASIC, Integer BASIC, is not 
supported under ProDOS. Indeed, Applesoft must be in the 
motherboard ROMs for the ProDOS BASIC Interpreter to 
work at all. This means that only the ProDOS Kernel, used ina 
standalone, run-time environment, will run on an original, 
Integer Apple II. It is likely that someone (probably not Apple) 
will soon market an Integer BASIC interpreter for ProDOS, 
however. 


@® ProDOS requires 64K to support BASIC programming and 
commands. [t can be made to run in 48K for run-time assembly 
language applications, but 64K is required to run the BASIC 
Interpreter which incorporates all of the ProDOS commands 
(e.g. CATALOG, BLOAD, etc.). 
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Under BASIC, less memory is available to the program. 
Under DOS, HIMEM was set at $9600 with three file buffers 
built into DOS. Under ProDOS, HIMEM is at $9600 with no 
file buffers built in. Thus, as soon as a ProDOS BASIC 
program opens a file, HIMEM is moved down and IK less 
memory is available. Likewise, since the Kernel occupies the 
Language Card (or bank switched memory), this space may 
not be used for other purposes. (DOS could be relocated into 
the language card to make more space available to BASIC 
programs. Also, Applesoft enhancement aid programs 
typically were loaded into the language card’s alternate 4K 
bank under DOS. This is where ProDOS stores its Quit code 
now.) 


ProDOS only maintains a single directory prefix for all 
volumes, rather than remembering a default prefix for each 
volume. Hence, diskette swapping and access to multiple 
volumes at once can be cumbersome. 


Although the pathname for a file may be 64 characters, the 
actual name of a file may be only 15 characters, and may not 
include any special characters or blanks (other than “period”). 
30 characters were permitted under DOS. 


Under DOS, up to 16 files may be opened concurrently by a 
BASIC program. Under ProDOS, only eight files may be 
opened at once. Also, an open file “cost” 595 bytes under DOS; 
under ProDOS, a 1024-byte buffer is allocated. 


BASIC programs which are computationally oriented will run 
about four percent slower on ProDOS than they did under 
DOS. This is because the ProDOS BASIC Interpreter leaves 
Applesoft TRACE running (invisibly) at all times so that it can 
monitor the execution of the program and perform garbage 
collection and disk commands. On the other hand, if strings or 
disk accesses are used, this degradation of performance will be 
more than offset by improvements in these areas. 


Several DOS commands have been removed, including 
NOMON, MON, and VERIFY. There is now no way to see the 
commands in an EXEC file as they are executed. 


If a ProDOS directory is destroyed, it is harder to reconstruct 
than was the DOS CATALOG track. More information is 
stored in the directory making it harder to identify a file’s type 
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by examining its data blocks. Also, since seedling files do not 
have index blocks (similar to DOS Track/Sector Lists), they 
are almost impossible to find once their directory entries are 
gone. 


OTHER DIFFERENCES BETWEEN ProDOS AND DOS 


There are a few other minor differences between ProDOS and 

DOS which are worth noting: 

@® The BRUN command now calls the target program rather 
than jumping to it as did DOS. The invoked program may 
return to ProDOS viaa return subroutine. 

@ CLOSE will not produce an error message if the file named is 
not currently open. 

@ APPEND implies WRITE. It is not necessary to follow an 
APPEND command with a WRITE command in a BASIC 
program. 

@ ASCII text in ProDOS directory entries or TXT files is stored 
with the most significant bit off. 


CHAPTER 3 


DISK Il HARDWARE 
AND DISKETTE FORMATTING 


This chapter will explain how data is stored on a floppy diskette 
using a disk drive (Disk II family or equivalent). Much of the 
information in this chapter is applicable not only to ProDOS but 
also to other operating systems on the Apple computer (DOS, 
PASCAL, CP/M). Because ProDOS isolates device specific code, 
the contents of this chapter should not be considered a prerequisite 
for understanding succeeding chapters. 

For system housekeeping, ProDOS divides external storage 
devices into blocks. Each block contains 512 bytes of information. 
It is device independent in that each device has its own driver. This 
driver enables ProDOS to read and write blocks, and additionally 
to obtain the status of a device. The device itself may actually store 
information in a number of ways and not necessarily in blocks. 
Blocks can be thought of as a conceptual unit of data that was 
created in software, having little or no relation to how data is 
actually stored on an external storage device. In fact, the standard 
Disk II stores information in a track and sector format. The device 
driver provides a mapping between these tracks and sectors, and 
the blocks. Since a sector contains 256 bytes, two sectors are 
required for each block. There are 560 sectors on a diskette and 
therefore 280 blocks. Chapter 4 deals with how ProDOS allocates 
these blocks to create files. 


3-2. Beneath Apple ProDOS 


TRACKS AND SECTORS 


As stated above, a diskette is divided into tracks and sectors. 
This is done during the initialization or formatting process. A 
track is a physically defined circular path which is concentric 
with the hole in the center of the diskette. Each track is identified 
by its distance from the center of the disk. Similar to a phonograph 
stylus, the read/write head of the disk drive may be positioned over 
any given track. The tracks are similar to the grooves ina record, 
but they are not connected in a spiral. Much like playing a record, 
the diskette is spun at a constant speed while the data is read from 
or written to its surface with the read/write head. Apple formats 
its diskettes into 35 tracks, numbered from 0 to 34, track 0 being 
the outermost track and track 34 the innermost. Figure 3.1 
illustrates the concept of tracks, although they are invisible to the 
eye on a real diskette. 

It should be pointed out, for the sake of accuracy, that the disk 
arm can position itself over 70 distinct locations or phases. To 
move the arm from one track to the next, two phases of the stepper 
motor which moves the arm must be cycled. This implies that data 
might be stored on 70 tracks, rather than 35. Unfortunately, the 
resolution of the read/write head is such that attempts to use these 
phantom half tracks create so much cross-talk that data is lost or 
overwritten. Although standard ProDOS uses only full tracks 
(even phases), some copy protected disks use half tracks (odd 
phases) or combinations of the two. This will work provided that no 
data is closer than two phases from other data. Se APPENDIX B 
for more information on copy protection schemes. 


TRACK 17 


TRACK 34 





ONE TRACK 


Figure 3.4 Tracks and Sectors 
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A sector is a subdivision of a track. It is the smallest unit of 
“updatable” data on the diskette. While ProDOS reads or writes 
data a block at a time (two sectors), the device driver operates on 
one sector at a time. This allows the device driver to use only a 
small portion of memory as a buffer during read or write 
operations. Apple has used two different track formats to date. The 
initial operating system divided the track into 13 sectors, but all 
recent operating systems use 16 sectors. The sectoring does not use 
the index hole, provided on most diskettes, to locate the first sector 
of the track. The implication is that the software must be able to 
locate any given track and sector with no help from the hardware. 
This scheme, known as soft sectoring, takes a little more space for 
storage but allows flexibility, as evidenced by the previous change 
from 18 sectors to 16 sectors per track. The following table 
categorizes the amount of data stored on a diskette under ProDOS. 
Both system and data diskettes are categorized. 


DISKETTE ORGANIZATION 


BYTES PER DISKETTE 

USABLE* BLOCKS FOR DATA STORAGE 
ProDOS System Diskette 
ProDOS Data Diskette 

USABLE* BYTES PER DISKETTE 
ProDOS System Diskette 
ProDOS Data Diskette 





*System Diskette includes PRODOS and BASIC.SYSTEM files only. 
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TRACK FORMATTING 


Up to this point we have broken down the structure of data to the 
track and sector level. To better understand how data is stored and 
retrieved, we will start at the bottom and work up. 

As this manual is about software (ProDOS), we will deal 
primarily with the function of the hardware rather than explain 
how it performs that function. For example, while data is in fact 
stored as a continuous stream of analog signals, we will deal with 
discrete digital data, i.e. a “0” or a “1”. We recognize that the 
hardware converts analog data to digital data, but how this is 
accomplished is beyond the scope of this manual. For a full and 
detailed explanation of the hardware, please refer to Jim Sather’s 
excellent book, Understanding the Apple IT, published by Quality 
Software. 

Data bits are recorded on the diskette in precise intervals. The 
hardware recognizes each of these intervals as either a “OQ” or a “1” 
We will define these intervals to be bit cells. A bit cell can be 
thought of as the distance the diskette moves in four machine 
cycles, which is about four microseconds. Using this 
representation, data written on and read back from the diskette 
takes the form shown in Figure 3.2. The data pattern shown 
represents a binary value of 101. 


BIT CELL 
4 psec 


DATA BITS 


Figure 3.2 Bits on Diskette 


Disk li Hardware and Diskette Formatting 3-5 


Ue Ls th ithe th Lr 


——bBIT GELLS =—— 
A byte as recorded on the disk consists of eight (8) consecutive bit 


cells. The most significant bit cell is usually referred to as bit cell 
7, and the least significant is bit cell 0. When reference is made to 
a specific data bit (i.e. data bit 5), it is with respect to the 
corresponding bit cell (bit cel! 5). Data is written and read serially, 
one bit at a time. Thus, during a write operation, bit cell 7 of each 
byte is written first, and bit cell 0 is written last. Correspondingly, 
when data is being read back from the diskette, bit cell 7 is read 
first and bit cell 0 is read last. Figure 3.3 illustrates the 
relationship of the bits within a byte. 

















Figure 3.3 One Byte on Diskette 
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To graphically show how bits are stored and retrieved, we must 
take certain liberties. The diagrams are a representation of what 
functionally occurs within the disk drive. For the purposes of our 
presentation, the hardware interface to the diskette will be repre- 
sented as an 8-bit data register. Since the hardware involves 
considerably more complication, from a software standpoint it is 
reasonable to use the data register, as it accurately embodies the 
function of data flow to and from the diskette. For a further 
discussion of the hardware, please see APPENDIX D. 

Figure 3.4 shows the three bits, 101, being read from the 
diskette data stream into the data register. Of course another five 
bits would be read to fill the register. 


DATA REGISTER 


‘BIT STREAM b= 0-0 


ID= 1 O=0 <4 
Seeeenoo 
D=4 0-0 jD= 


Figure 3.4 Reading Data from a Diskette 
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Writing data can be depicted in much the same way (see Figure 
3.5). It should be noted that, while in write mode, zeroes are being 
brought into the data register to replace the data being written. It 
is the task of the software to make sure that the register is loaded 
and instructed to write in 32-cycle (microsecond) intervals. If not, 
zero bits will continue to be written every four cycles, which is in 
fact exactly how self-syne bytes are created. Self-sync bytes will be 
covered in detail shortly. 


DATA REGISTER 
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Figure 3.5 Writing Data to a Diskette 
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A field is made up of a group of consecutive bytes. The number 
of bytes varies, depending upon the nature of the field. The two 
types of fields present on a diskette are the Address Field and the 
Data Field. They are similar in that they both contain a prologue, 
a data area, a checksum, and an epilogue. Each field on a track is 
separated from adjacent fields by a number of bytes. These areas 
of separation are called gaps and are provided for two reasons. 
First, they allow the updating of one field without affecting 
adjacent fields (on the Apple, only data fields are updated). 
Secondly, they allow the computer time to decode the address field 
before the corresponding data field can pass beneath the 
read/write head. 

All gaps are primarily alike in content, consisting of self-sync 
hexadecimal FF’s, and vary only in the number of bytes they 
contain. Figure 3.6 is a diagram of a portion of a typical track, 
broken into its major components. 










ODRESS GAP 2 | OATAFIELD | GaP3 jADORES: 
FIELD 
=O a0 








HEX FF SYNC BYTES 
VPICALLY $-10 


Figure 3.6 Track Format 


Self-syne or auto-sync bytes are special bytes that make up the 
three different types of gaps on a track. They are so named because 
of their ability to automatically bring the hardware into 
synchronization with data bytes on the disk. The difficulty in doing 
this lies in the fact that the hardware reads bits, and the data must 
be stored as 8-bit bytes. It has been mentioned that a track is 
literally a continuous stream of data bits. In fact, at the bit level, 
there is no way to determine where a byte starts or ends, because 
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By The Ol] BI Stream 


each bit cell is exactly the same, written in precise intervals with 
its neighbors. When the drive is instructed to read data, it will 
start wherever it happens to be on a particular track. That could 
be anywhere among the 50,000 or so bits on a track. The hardware 
finds the first bit cell with data in it and proceeds to read the 
following seven data bits into the 8-bit register. In effect, it 
assumes that it had started at the beginning of a data byte. Of 
course, in reality, it could have started at any of the “1” bits of the 
byte. Pictured in Figure 3.7 is a small portion of a track. 


0110101110101100111101101110101 


Figure 3.7 An Example Bit Stream on the Diskette 


From looking at the data, there is no way to tell what bytes are 
represented, because we don’t know where to start. This is exactly 
the problem that self-sync bytes overcome. 

A self-sync byte is defined to be a hexadecimal FF witha 
special difference. It is, in fact, a 10-bit byte rather than an 8-bit 
byte. Its two extra bits are zeroes. Figure 3.8 shows the difference 
between a normal data hex FF that might be found elsewhere on 
the disk and a self-syne hex FF byte. 
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NORMAL BYTE HEX FF SELF-SYNC BYTE HEX FF 





Figure 3.8 Comparison Between a Normal Byte and a Self-Syne 
Byte 


A self-syne byte is generated by using a 40-cycle (microsecond) 
loop while writing an FF. A bit is written every four cycles, so two 
of the zero bits brought into the data register while the FF was 
being written are also written to the disk, making the 10-bit byte. 
It can be shown, using Figure 3.9, that four self-sync bytes are 
sufficient to guarantee that the hardware is reading valid data. 
The reason for this is that the hardware requires the first bit of a 
byte to be a “1”. Pictured at the top of the figure is a stream of four 
self-syne bytes followed by a normal FF. Each row below that 
demonstrates what the hardware will read should it start reading 
at any given bit in the first byte. In each case, by the time the four 
sync bytes have passed beneath the read/write head, the hardware 
will be syneed to read the data bytes that follow. As long as the 
disk is left in read mode, it will continue to correctly interpret the 
data unless there is an error on the track. 


THUPATTTOOTALVI71ITOOTAATLVATOONVTAAATIOO1A1IADNI 
ERTTTT To of TET TTT Ho oT TTT Yo of T TTI To of TTT 
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1a ETT TOIT ATT To FETT To of TTT TTT To of TTT 
1441 GTETOOT ITT TTT OORT TTT Ho of PETTITT Ho oft TT IIT 
y114 tPTTOO TPT TOO AT TTT Vo PTT TTT T io ofr tT} 
Eh STS Si oe ed a | 
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Figure 3.9 Self-Sync Bytes 
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We can now discuss the particular portions of a track in detail. 
The three gaps will be covered first. Unlike some other disk 
formats, the size of the three gap types will vary from drive to 
drive and even from track to track. During the formatting process, 
ProDOS will start with large gaps and keep making them smaller 
until an entire track can be written without overlapping itself. A 
minimum number of self-syne bytes is maintained for each gap 
type. The result is fairly uniform gap sizes within each particular 
track. 

Gap 1 is the first data written to a track during initialization. Its 
purpose is twofold. The gap originally consists of 128 self-syne 
bytes, a large enough area to insure that all portions of a track will 
contain data. Since the speed of a particular drive may vary, the 
total length of the track in bytes is uncertain, and the percentage 
occupied by data is unknown. The initialization process is set up, 
however, so that even on drives of differing speeds, the last data 
field written will overlap Gap 1, providing continuity over the 
entire physical track. Unlike earlier operating systems, ProDOS 
will let you know if your drive is too fast or too slow. The remaining 
portion of Gap 1 must be approximately 75% as long as a Gap 3 on 
that track, enabling it to serve as a Gap 3 type for Address Field 
number 0 (See Figure 3.6 for clarity). 

Gap 2 appears after each Address Field and before each Data 
Field. Its primary purpose is to provide time for the information in 
an Address Field to be decoded by the computer before a read or 
write takes place. If the gap was too short, the beginning of the 
Data Field might spin past while ProDOS was still determining if 
this was the sector to be read. The 200 cycles that five self-sync 
bytes provide seems ample time to decode an Address Field. When 
a Data Field is written, there is no guarantee that the write will 
occur in exactly the same spot each time. This is due to the fact that 
the drive which is rewriting the Data Field may not be the one 
which originally formatted or wrote it. Since the speed of the 
drives can vary, it is possible that the write could start in mid-byte 
(see Figure 3.10). For this reason, the length of Gap 2 varies from 
five to ten bytes. This is not a problem as long as the difference in 
positioning is not great. To insure the integrity of Gap 2 when 
writing a data field, five self-syne bytes are written prior to 
writing the Data Field itself. This serves two purposes. Since 


3-42 Beneath Apple ProDOS 


ADDRESS CURRENT 


I 
l 

FIELD ! DATA 
; FIELD 





NEW 
DATA 
FIELD 


Figure 3.10 ProDOS Doesn't Aiways Write in the Same Place 


relatively little time is spent decoding an address field, the five 
bytes help place the Data Field near its original position. Secondly, 
and more importantly, the five self-syne bytes are the minimum 
number required to guarantee read-synchronization. It is probable 
that, in writing a Data Field, at least one sync byte will be 
destroyed. This is because, just as in reading bits on the track, the 
write may not begin on a byte boundary, thus altering an existing 
byte. Figure 3.11 illustrates this. 


Before 


L write starts here 


After 


Cg agg 


Figure 3.14 Writing Out of Sync 
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Gap 3 appears after each Data Field and before each Address 
Field. It is longer than Gap 2 and care is taken to make sure it 
ranges from 16 to 28 bytes in length. It is quite similar in purpose 
to Gap 2. Gap 3 allows the additional time needed to manipulate 
the data that has been read before the next sector is to be read. The 
length of Gap 3 is not as critical as that of Gap 2. If the following 
Address Field is missed, ProDOS can always wait for the next 
time it spins around under the read/write head (one revolution of 
the disk at most). Since Address Fields are never rewritten, there 
is no problem with Gap 8 providing synchronization, since only the 
first part of the gap can be overwritten or damaged (see Figure 
3.10 for clarity). 


ADDRESS FIELDS 

An examination of the contents of the two types of fields is in 
order. The Address Field contains the address or identifying 
information about the Data Field which follows it. The volume, 
track, and sector number of any given sector can be thought of as 
its “address,” much like a country, city, and street number might. 
identify a house. As shown previously in Figure 3.6, there area 
number of components which make up the Address Field. A more 
detailed illustration is given in Figure 3.12. 


PROLOGUE VOLUME TRACK SECTOR CHECKSUM EPILOGUE 


Figure 3.12 Address Field 


Each byte of the Address Field is encoded into two bytes when 
written to the disk. APPENDIX C describes the “4 and 4” method 
used for Address Field encoding. 
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The prologue consists of three bytes which form a unique 
sequence, found in no other component of the track. This fact 
enables ProDOS to locate an Address Field with almost no 
possibility of error. The three bytes are $D5, $AA, and $96. The 
$D5 and $AA are reserved (never written as data), thus insuring 
the uniqueness of the prologue. The $96, following this unique 
string, indicates that the data following constitutes an Address 
Field (as opposed to a Data Field). The address information follows 
next, consisting of the volume’, track, and sector number and a 
checksum. This information is absolutely essential for ProDOS to 
know where it is positioned on a particular diskette. The 
checksum is computed by exclusive-ORing the first three pieces of 
information, and is used to verify its integrity. Lastly follows the 
epilogue, which contains the three bytes $DE, $AA and $EB. The 
$EB is only partly written during initialization, and is therefore 
never verified when an Address Field is read. The epilogue bytes 
are sometimes referred to as bit-slip marks, which provide added 
assurance that the drive is still in syne with the bytes on the disk. 
These bytes are probably unnecessary, but do provide a means of 
double checking. 


DATA FIELDS 


The other field type is the Data Field. Much like the Address 
Field, it consists of a prologue, data, checksum, and an epilogue 
(refer to Figure 3.13). The prologue differs only in the third byte. 
The bytes are $D5, $AA, and $AD, which again form a unique 
sequence, enabling ProDOS to locate the beginning of the sector 
data. The data consists of 342 bytes of encoded data. (The encoding 
scheme used is quite complex and is documented in detail in 
APPENDIX C.) The data is followed by a checksum byte, used to 
verify the integrity of the data just read. The epilogue portion of 
the Data Field is absolutely identical to the epilogue in the Address 
Field and serves the same function. 


PROLOGUE USER DATA CHECKSUM EPILOGUE 


D5 AA AD| 342BYTESDATA | Xxx |DE AAEB 
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Figure 3.13 Data Field 


*Volume number is a leftover from earlier operating systems and is not used by 
ProDOS. 
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DISK Il BLOCK AND SECTOR INTERLEAVING 


Because the disk drive is such an integral part of the Apple II 
family of machines, it is important that it perform efficiently. One 
major factor in disk drive performance is how the data is arranged 
on the diskette. Because the diskette spins and the head that reads 
and writes the data is stationary, it is necessary to wait fora 
particular portion of a given track to pass by. This waiting 
(rotational delay) can add significant time to a disk access if the 
data is poorly arranged. Interleaving (or skewing) is the 
arranging of data at the block or sector level to maximize access 
speed. It effectively places a gap between blocks or sectors that 
will normally be accessed sequentially, allowing sufficient time for 
internal housekeeping before the next one appears. In general, if 
blocks or sectors are poorly arranged on a track, it is usually 
necessary to wait an entire revolution of the diskette before the 
next desired block or sector can be accessed. 

The first versions of Apple’s operating system used physical 
interleaving on the disk. (That is, sectors were written ina 
particular order on the diskette.) A number of different schemes 
were used in an attempt to maximize performance. This worked 
reasonably well but, because different methods were used for 
different operations, performance suffered. Later versions 
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standardized the physical interleaving (as sequential), and used a 
software method to try to maximize performance. An attempt was 
also made to standardize some operations, but performance still 
was not optimal as evidenced by a proliferation of “fast” DOS’s. 

ProDOS provides an impressive improvement over Apple’s 
earlier operating systems. Several factors account for the 
dramatic improvement. The routine to read data is significantly 
faster, minimizing the delay occurring between read operations. 
The data is dealt with in larger pieces (512 bytes vs. 256 bytes), 
lowering the number of requests to the code that actually reads 
and writes data (Device Driver). And almost all operations 
involve files stored on sequential blocks. As a disk begins to get 
full, this will not always be possible and some files will be 
discontinuous; but for the most part, all operations (loading 
ProDOS or Applesoft BASIC, reading or writing to files or a 
directory) involve data in contiguous pieces. This greatly 
simplifies the problem of finding an optimal interleaving for disk 
accesses. 

In ProDOS, the interleaving is done in software. The 16 sectors 
are in numerically ascending order on the diskette (0, 1, 2,... 15), 
and are not physically interleaved at all. An algorithm is used to 
translate block numbers into physical sector numbers used by the 
ProDOS device driver. For example, if the block number 
requested were 2, this would be translated to track 0, physical 
sectors 8 and A.* Figure 3.14 illustrates the concept of software 
interleaving and Table 3.1 shows the mapping of physical sectors 
to blocks for a Disk II or compatible drive. 

There are two kinds of interleaving to consider in the case of 
ProDOS. First, there is the interleaving of the two sectors that 
make up a block. This will be referred to as intra-block or 
“within block” interleaving. Second, there is the interleaving 
between blocks on a given track. This will be referred to as inter- 
block or “between block” interleaving. It should be noted that we 
are concerned primarily with delays within ProDOS and the Disk 
II Device Driver, and not with delays that may be present in 
various application packages. 


*Those familiar with DOS 3.3 should note that physical sector numbers and DOS 
3.3 sector numbers are not the same. Most “disk utilities” use DOS 3.3 sector 
numbers and not physical sector numbers. The bottom of Table 3.1 shows how 
DOS 3.8 sector numbers are related to ProDOS block numbers. 
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Table 3.4 ProDOS Block Conversion Table for Diskettes 
PHYSICAL SECTOR 
0&2 4&6 8&A C&E 1&3 5&7 9&B D&F 
TRACK O 000 001 002 003 004 005 006 007 
TRACK 1 008 009 00A 00B 00C 00D 00E 00F 
TRACK2 010 01 012 013 014 015 016 017 
TRACK 3 018 019. OIA O01IB.0iC. OID 01k OIF 
TRACK 4 020 021 022 023 024 025 026 027 


TRACK 5 028 029 02A 02B 02C 02D 02E 02F 
TRACK7 


038 


039 


03A 


03B 


03C 


03D 


08E 








03F 

































































































































070 071 072 073 074 075 076 077 

078 079 O7A 07B 07C 07D OTE O7F 

TRACK 10 080 081 082 083 084 085 O86 087 
TRACK 11 088 089 O8A 08B O08C 08D O8E O8F 
TRACK 12 090 091 992 093 094 095 096 097 
TRACK 13 098 699 O9A 09B 99C 09D 09E 09oF 
TRACK 14 0A0 OAl 0A2 0A3 0A4 OA5 0A6 OAT 
TRACK 15 OA8 GA9 OAA 0OAB GAC 0AD OAE OAF 
TRACK 16 OBO ORI OB2 OB3 0B4 OB5 OB6 OB7 
OB8 OBS OBA OBB OBC OBD OBE OBF 
TRACK 18 0CO 0ci 0c2 0C3 0C4 0C5 0cé 0C7 
TRACK 19 0C8 0c9 OCA 0CB occ ocD 0OCE OCF 
TRACK 1A ODO oD1 OD2 0D3 0D4 OD5 ods 0D7 
TRACK 1B 0D8 0D9 ODA ODB oDC ODD ODE ODF 
TRACK IC 0EO OF1 OR2 0F3 04 OF5 OE6 OE7 
TRACK 1D OE8 OE9 OEA OEB 0EC OED OEE OEF 
TRACK 1E OFO OF 1 OF2 OF3 OF 4 OFS OF6 OF7 
TRACK 1F OF8 OF9 OFA OFB OFC OFD OFE OFF 

TRACK 20 100 101 102 108 104 105 106 107 
TRACK 21 108 109 10A 10B 10C 10D 10E 1OF 
TRACK 22 110 11 112 1138 114 115 116 117 
O&E D&C B&A 9&8 7&6 5&4 3&2 1&F 

DOS 3.3 SECTOR 
BLOCKS 
no. , 


SECTORS 





/ A 3/16 Rotation of the Disk is Necessary 


to Read or Write One Block 


Figure 3.44 Block interleaving (Track 0) 
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INTRA-BLOCK INTERLEAVING 


When ProDOS accesses a block, it must of course access the two 
sectors that make up that block. There is a small delay after the 
device driver has accessed the first sector, before it can access the 
second sector. This delay is different for Read and Write 
operations. The Read operation is so fast that the disk can read two 
sectors ina row. However, the Write operation takes longer, so for 
optimal performance there must be a gap between the two sectors 
that make up a block. If there wasn’t a gap, an entire revolution of 
the diskette would be required for each block written. A single 
sector provides a sufficient gap, so intra-block interleaving (within 
the block) consists of one sector. The result is that ProDOS is able 
to write to a given block as rapidly as is possible. Some time is lost 
when reading a block, but no other interleaving scheme would 
provide the same overall efficiency. Intra-block interleaving is 
illustrated in Figure 3.15. 


INTRA-BLOCK GAP = 1 SECTOR 





BLOCK 0 





Figure 3.15 Intra-Block Interleaving (Within Block) 


INTER-BLOCK INTERLEAVING 


When ProDOS accesses a number of blocks as required in most 
disk operations (i.e. reading or writing a directory or a file), 
another kind of interleaving is involved. There will be a delay 
between accesses, but it is now between blocks rather than sectors. 
There is relatively little difference in delay time in the MLI itself 
between reading and writing—almost all the difference occurs in 
the device driver. However, when ProDOS writes a block that is 
already allocated (i.e. part of an existing directory or file), it 
always reads that block before writing to it. This requires an 
entire revolution of the diskette regardless of how the interleaving 
is done. It turns out that, just as for intra-block operations, a single 
sector is a sufficient gap for reading blocks. Inter-block 
interleaving is illustrated in Figure 3.16. 
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READING OR WRITING A BLOCK 


Assume that we wish to access block 2. ProDOS passes the 
request to the device driver which in turn converts the block 
number into its track and sector representation (see Figure 3.14). . 
The arm is moved to the proper track (0) and then a sector is read. 
This could be any sector, because the diskette is spinning. Sectors 
are continually read until sector 8 is found. The following two 
sectors are then read (9 and A) which completes the read of block 2 
(sectors 8 and A). Depending on where we start on the track, we 
could read between 3 and 18 sectors. The same process occurs 
when writing a single block, with one small difference. After 
sector 8 is located and written to, the delay required to ready the 
data for sector A will cause us to miss reading sector 9. This does 
not alter the amount of rotation necessary to complete the task. To 
summarize, the time required to either read or write a single block 
consists of two factors. (We are assuming the track has already 
been located). First, there is the time required to locate the first 
sector of the block—this is variable and ranges between 0 and the 
time of one full rotation of the diskette. Second is the time required 
to actually read or write the two sectors that make up the block— 
this is fixed and always requires 3/16 rotation of the diskette. 


INTER-BLOCK GAP = 1 SECTOR 





BLOCK 0 


BLOCK 4 


Figure 3.46 Inter-Block interleaving (Between Block) 
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READING OR WRITING CONSECUTIVE BLOCKS 


Let’s examine what occurs when a number of blocks are accessed 
during reading or writing of a typical file. We will assume the file 
is reasonably large and takes up a number of blocks. We will 
confine our observation to a single track, in which eight blocks 
comprise the file of interest. We will assume track 2, which 
contains blocks 10 through 17 (as in Figure 3.17), and we will 
further assume that the blocks will be accessed sequentially. When 
the read/write head moves to track 2, we will start reading sectors 
until the appropriate sector is found (0 in this case). Then each 
sector is read until all eight blocks are found. This will require 
exactly two revolutions of the disk. Writing takes significantly 
longer because each block is read before being written to. 
Therefore, once the first sector of the block in question is located, 
one entire revolution is necessary to write each block. Upon 
writing a block, ProDOS is able to locate the next block 
immediately, read it, wait through one revolution and write it. A 
total of ten revolutions is required to write an entire track as 
opposed to two revolutions to read it. 
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Figure 3.47 Example: The Block interleaving of Track 2 


CHAPTER 4 


VOLUMES, DIRECTORIES, AND FILES 


As was described in Chapter 3, a 16-sector diskette consists of 
560 data areas of 256 bytes each, called sectors. These sectors are 
arranged on the diskette in 35 concentric rings, called tracks, of 16 
sectors each. The way ProDOS allocates these tracks of sectors is 
the subject of this chapter. 


THE DISKETTE VOLUME 


ProDOS defines a volume to be any (usually direct aceess) indi- 
vidual mass storage media. The discussion which follows assumes 
this media to be a single 35-track diskette, but all of the structures 
presented here are identical for other diskette sizes and even for a 
hard disk such as the Apple ProFile. Another interesting point is 
that the structure of a ProDOS volume is almost identical to that of 
an Apple III SOS volume. This fact allows greater data compati- 
bility between the two operating systems. 

To make the allocation of sectors more manageable, ProDOS 
pairs them up to form 512-byte blocks. Since there are 16 sectors 
per track and 560 sectors per diskette volume, there are eight 
blocks per track and 280 blocks per volume. These blocks are 
numbered from 0 to 279 (decimal) or $0000 to $0117 (hexadec- 
imal). The arrangement of blocks on a diskette is shown in Figure 
4.1. Of course, on a real diskette, skewing (discussed in Chapter 3) 
would reorder the blocks on any given track, but, for the purposes 
of this discussion, the blocks can be assumed to be stored 
sequentially. 
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Figure 4.4 Blocks on a Diskette 


A file, be it BAS, BIN, TXT, or SYS type, consists of one or more 
blocks containing data. Since a block is the smallest unit of allocat- 
able space on a ProDOS volume, a file will use up at least one block 
even if it is less than 512 bytes long; the remainder of the block is 
wasted. Thus, a file containing 600 characters.or bytes) of data 
will occupy one entire block and 88 bytes of another with 424 bytes 
wasted. Knowing that there are 280 blocks on a diskette, one might 
expect to be able to use up to 280 times 512 or 143,360 bytes of 
space on a diskette for files. Actually, the largest file that can be 
stored is 271 blocks long (or 138,752 bytes). The reason for this is 
that some of the blocks on the diskette volume must be used for 
what is called overhead. 
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VOLUME OVERHEAD 


Overhead blocks contain the image of the ProDOS bootstrap 
loader (which is loaded by the ROM on your diskette controller 
card and, in turn, loads the ProDOS system files into memory), a 
list of file names and locations of the files on the diskette, and an 
accounting of the blocks which are free for use by new files or for 
expansions of existing ones. An example of the way ProDOS uses 
blocks is given in Figure 4.2. 

Notice that in the case of this diskette volume, system overhead 
(that part of the diskette which does not actually contain files) falls 
entirely on track 0 of the diskette (blocks 0 through 7). In fact, 
there is room for one block’s worth of file data on track 0 (block 7). 
The first block (block 0) is always devoted to the image of the 
bootstrap loader. (Block 1 is the SOS bootstrap loader.) Following 
these, and always starting at block 2, is the Volume Directory. 
The Volume Directory is the “anchor” of the entire volume. On any 
diskette (or hard disk for that matter) for any version of ProDOS, 
the first or “key” block of the Volume Directory is always in the 
same place—block 2. Since files can end up anywhere on the 
diskette, it is through the Volume Directory key block that 
ProDOS is able to find them. Thus, just as the card catalog is used 
to locate a book ina library, the Volume Directory is the master 
index to all of the files on a volume. In addition to describing the 
name, attributes and placement of each file, it also contains the 
block number of the Volume Bit Map which will be described 


/EXAMPLE 

NAME TYPE BLOCKS MODIFIED CREATED ENDFILE SUBTYPE 
BASFILE BAS 1 <NO DATE> <NO DATE> 109 
TXTFILE TXT 1 <NO DATE> <NO DATE> 9 R= 64 
BINFILE BIN 1 <NO DATE> <NO DATE> 48 A=$03D0 
BLOCKS FREE: 270 BLOCKS USED: 10 TOTAL BLOCKS: 280 
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Figure 4.2 Block Usage on an Example Diskette 
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next. The first four bytes of every Volume Directory block are 
reserved for “pointers” to (the block numbers of) the previous 
Volume Directory block and the next Volume Directory block. This 
structure is called a doubly-linked list and is handy in that, from 
any block, it is easy to move forward or backward through the 
directory entries. The Volume Directory and Volume Bit Map are 
diagrammed in Figure 4.3. 


POINTERS TO 

FILES 

OR 
SUBDIRECTORIES 








BLOCK 2 









VOLUME 
DIRECTORY 
KEY BLOCK 









BLOCK 3 






NEXT 13 
ENTRIES 






BLOCK 4 





BLOCK 5 





BLOCK 6 





VOLUME BIT 
MAP 





Figure 4.3 Linking of Volume Directory and Volume Bit Map 


Volumes, Directories, and Files 4-5 


VOLUME SPACE ALLOCATION—THE VOLUME BIT MAP 


When a diskette volume is first formatted, only the first seven 
blocks described above are marked in use. All of the remainder of 
the diskette blocks are considered “free” for use with files yet to be 
created. Each time a new block is required for a file, the free block 
with the lowest number is used. To keep track of which blocks have 
been used and which are free, ProDOS maintains one block as the 
Volume Bit Map. The Volume Bit Map is located by following a 
pointer in the Volume Directory, however, it is almost always in 
block 6. It consists of 512 bytes, each byte representing eight 
blocks on the volume. If the bytes are examined in binary form, 
each consists of eight bits having a value of one or zero. Thus, if 
block zero is in use as it always is, then the first byte’s first bit is set 
to zero. If the ninth block (block 8) is free, then the first bit of the 
second byte is set to one. Since there are many more bits in the 
Volume Bit Map (4096 bits in all) than there could ever be blocks 
ona diskette, only the first 280 (or 35 bytes) are used. Fora 
5-megabyte hard disk, like the Apple ProFile, 1241 bytes are 
needed; in this case, since the number of blocks on the volume is 
stored in the Volume Directory, ProDOS automatically knows to 
expect a bigger Volume Bit Map—one which is three blocks long. 
Bits which do not correspond to a real block (because it would be 
past the end of the volume) are set to zero. An example of a Volume 
Bit Map for the volume mapped in Figure 4.2, is given in Figure 
4.4, Notice that, since three 1-block files have been allocated, a 
total of ten blocks are marked “in use.” 


Blocks ee In Use Blocks $A—$117 Free 


0000 Senger 0011 1111 1411 1101 1114 


IZ 


00 OO3FPFFPFEFFFPFFPFFFFFFE 
OC FRFFFFFFFFFFFFPFPFPPFFFF 
18 FFFFFFFFFFFFFFFFFFFFFFOO _ . 
24 GOGOCOPGGOSGGGGDDGGBBGOBG ..... weer 
30 O@OCOCBCOSPGBCCOGBOGGGGGGGG .......- eee 
3C OOGOOSOGGGCGGOGGOGBGBOGG ......-42--- 


(Remainder of Block Zeroes) 






Figure 4.4 Example Volume Bit Map 


4-6 Beneath Apple ProDOS 


THE VOLUME DIRECTORY 


When ProDOS must find a specified file by name, it first reads 
block 2 of the diskette, the key block of the Volume Directory. If 
the file name is not found in this block, the next directory block is 
read, following the pointer in the third and fourth bytes of the cur- 
rent block. Typically, the Volume Directory blocks occupy blocks 2 
through 5 of a volume. Of course, as long as a block number pointer 
exists, linking one block to the next, and the first Volume Directory 
block is block 2, ProDOS does not really care where the rest of the 
directory blocks are located. Figure 4.5 diagrams the Volume 
Directory for the example given in Figure 4.2. The figure shows 
the “next block” pointer (bytes +2 and +3 in the block) of block 2 in 
the Volume Directory, as an arrow pointing to block 3. Each block, 
in turn, has block numbers in the same relative location (+0,+1 and 
+2,+8) which point backward to the previous block and forward to 
the next block respectively. If no previous or next block exists, a 
block number of zero is used to indicate this (block 0, being part of 
the boot image, would never be a valid block number for a direc- 
tory or file block, so this is a safe convention). The first block in the 
Volume Directory (the key block) contains a special entry called 
the header which describes the directory itself and the character- 
istics of the volume, ete. This is followed by 12 file descriptive 






i 


_ SUPERVISOR | 





ya 


" DIRECTORY ASSISTANCE 
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BASFILE 


TXTFILE 
BINFILE 









BLOCK 2 






FIRST 12 
FILENAMES 

















BLOCK 3 






SECOND 13 
FILENAMES 





BLOCK 4 





THIRD 13 
FILENAMES 


BLOCK 5 





LAST 13 
FILENAMES 


Figure 4.5 The Volume Directory 


entries. All Volume Directory blocks other than the key block con- 
tain descriptions of up to 13 files each. (In practice, these entries 
can also be used to describe subdirectories, but this will be covered 
in detail later in the chapter.) Thus, with four Volume Directory 
blocks, a total of 4 times 13 less 1 (for the Volume Directory Header 
entry) or 51 files may be described. 
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THE VOLUME DIRECTORY HEADER 

The Volume Directory Header is the first entry in the first block 
of the Volume Directory. As such, its first byte follows the four 
bytes of next/previous block pointers, so its first byte is at +$04. A 
description of its format follows:* 


yi DESCRIPTION = 


$04 STORAGE_TYPE/NAME LENGTH: 1 The first nibble 
(top four bits) of this byte describes the type of entry. In 
this case, this is a Volume Directory Header so this nib- 
ble is $F. The low four bits are the length of the name in 
the next field (the volume name). 

$05-$18 VOLUME_NAME: A 15-byte field containing the name 
of this volume. The actual length is defined by 
NAME_LENGTH above; the remainder of the field is 
ignored. No “/” is present as the first character since this 
is only used to delimit different level names but is not 
part of the names themselves. 

$14-$1B Reserved for future use. Usually zeroes. 

$1C-$1F CREATION: The date and time of the creation (format- 
ting) of this volume. This field is zero if no date was 
assigned. The format of the field is as follows: 


BYTE 0 and l—yyyyyyymmmmddddd _ year/month/day 
BYTE 2and 3—000hhhhh0Ommmmmm hours/minutes 


where each letter above represents one binary bit. This 
is the standard form for all create and modify date/time 
stamps in directories. 

$20 VERSION: The ProDOS version number under which 
this volume was formatted. This field tells later versions 
of ProDOS not to expect to find any fields which were 
defined by Apple after this version of ProDOS was 
released. This field indicates the level of upward com- 
patibility between versions. Under ProDOS 1.0, its 
value is zero. 





*Unless otherwise indicated, all multiple byte numeric values, such as block 
numbers, EOF marks, etc., are stored least significant byte first, most significant 
byte last (LO/HD. 


$21 


$22 


$23 


$24 


$25-$26 


$27-$28 


$29-$2A 
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MIN_VERSION: Minimum version of ProDOS which 
can access this volume. A value in this field implies that 
significant changes were made to the field definitions 
since prior versions of ProDOS were in use and these 
older versions would not be able to successfully interpret 
the file structure of this. volume. This field indicates the 
level of downward compatibility between versions. 
Under ProDOS 1.0, its value is zero. 


ACCESS: The bits in the flag byte define how the direc- 
tory may be accessed. The bit assignments are as 
follows: 


$80 — Volume may be destroyed (reformatted) 

$40 — Volume may be renamed 

$20 — Volume directory has changed since last backup 
$02 — Volume directory may be written to 

$01— Volume directory may be read 


All other bits are reserved for future use. 


ENTRY_LENGTH: Length of each entry in the Volume 
Directory in bytes (usually $27). 


ENTRIES_PER_BLOCK: Number of entries in each 
block of the Volume Directory (usually $0D). Note that 
the Volume Directory Header is considered to be an 
entry. 


FILE_COUNT: Number of active entries in the Volume 
Directory. An active entry is one which describes a file 
or subdirectory which has not been deleted. This count 
does not include the Volume Directory Header. Note 
that this field’s name is a bit misleading since the count 
also includes subdirectory entries. 


BIT_MAP_POINTER: The block number of the first 
block of the Volume Bit Map described earlier. This 
value is usually 6. 


TOTAL_BLOCKS: The total number of blocks on this 
volume. $0118 is for a 35-track diskette (280 decimal). 
This number may be used to compute the number of 
blocks in the Volume Bit Map as described earlier. 
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FILE DESCRIPTIVE ENTRIES 


Each file (or subdirectory) on a volume has a File Descriptive 
Entry in the Volume Directory or another directory. These entries 
all have the same format: 






oath ey BE SBN 


$00 STORAGE_TYPE/NAME_LENGTH: The first nibble 
(top four bits) of this byte describes the type of entry. 
Currently assigned values are: 


$0 = Deleted entry. Available for reuse 

$1 = File isa seedling (only one data block) 

File is a sapling (2 to 256 data blocks) 

File is a tree (257 to 32768 data blocks) 

$D = File isa subdirectory 

$E = Reserved for Subdirectory Header entry 

$F = Reserved for Volume Directory Header entry 
The low four bits are the length of the file or subdirec- 
tory name in the next field. When a file is deleted, a $00 
is stored in this byte. 


LA 
bh 
nou 


$01-0F FILE_NAME: A 15-byte field containing the name of 
this file. The actual length is defined by NAME_LENGTH 
above; the remainder of the field is ignored. 


$10 FILE_TYPE: Primary file type. The hexadecimal value 
of this byte gives the file type as shown in the following 
table: 


TYPE | NAME | DESCRIPTION 


Typeless file 

Bad block(s) file 

Text file (ASCII text, msb off) 
Binary file (8-bit binary image) 
Directory file 

AppleWorks data base file 
AppleWorks word processing file 
AppleWorks spreadsheet file 
ProDOS PASCAL file 
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ProDOS added command file 
User defined file types 1 through 8 
Applesoft BASIC program file 
Applesoft stored variables file 
Relocatable object module file 
(EDASM) 

ProDOS system file 









All other types are either SOS file types or are reserved 
by Apple for future use. See APPENDIX E fora 
complete list. 


$11-$12 KEY_POINTER: The block number of the key block of 
the file. In the case of a seedling file, this is the block 
number of the only data block. For saplings, this is the 
block number of the index block. For tree files, this is 
the block number of the master index block. (More on 
these file structures later.) If the file is a subdirectory 
file, this is the block number of its first block. 

$13-$14 BLOCKS_USED: The total number of blocks used by 
this file including index blocks and data blocks. If the 
file is a subdirectory, this is the number of directory 
blocks. 

$15-$17 EOF: The location of the end of the file(KOF)asa 
3-byte offset from the first byte. This can also be thought 
of as the length in bytes of a sequential file. 

$18-$1B CREATION: The date and time of the creation of this 
file. This field is zero if no date was assigned. The format 
of the field is as follows: 


BYTE 0 and 1—yyyyyyymmmmddddd _year/month/day 
BYTE 2 and 3—000hhhhh0OOmmmmmm hours/minutes 


where each letter above represents one binary bit. This 
is the standard form for all create and modify date/time 
stamps in directories. 

$1C VERSION: The ProDOS version number under which 
this file was created. This field tells later versions of 
ProDOS not to expect to find any fields which were 
defined by Apple after this version of ProDOS was 
released. This field indicates the level of upward com- 
patibility between versions. Under ProDOS 1.0, its 
value is zero. 
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$1D MIN_VERSION: Minimum version of ProDOS which 
can access this file. A value in this field implies that sig- 
nificant changes were made to the file structure defini- 
tion since prior versions of ProDOS were in use, and 
these older versions would not be able to successfully 
interpret the file structure of this file. This field indi- 
cates the level of downward compatibility between ver- 
sions. Under ProDOS 1.0, its value is zero. 

$1E ACCESS: The bits in this flag byte define how the file 
may be accessed. The bit assignments are as follows: 


$80 — File may be destroyed 

$40 — File may be renamed 

$20 — File has changed since last backup 
$02 — File may be written to 

$01 — File may be read 


All other bits are reserved for future use. An unlocked 
file’s ACCESS is usually $C3. Ifa file is locked, 
ACCESS will be set to $01. Subdirectory files which 
have a non-zero FILE_COUNT field will be locked until 
all files described by them are deleted. 

$1F-$20 AUX_TYPE: Auxiliary type field whose contents 
depend upon FILE_TYPE. Common uses are as follows: 


Random access record length (L from OPEN) 
Load address for binary image (A from BSAVE) 
Load address for program image (when SAVEd) 


Address of compressed variables image (when 
STOREd 

Load address for system program (usually 
$2000) 





$21-$24 LAST_MOD: Date and time at which file was last modi- 
fied. This field is zero if no date was assigned. Format is 
identical to CREATION above. 

$25-§26 HEADER_POINTER: Block number of the key block 
for the directory which describes this file. 


Figure 4.6 is an example of a typical Volume Directory block for 
the example introduced with Figure 4.2. In this case, there are 
only three files on the diskette so only the first three directory 
entries are filled in. The remaining directory entries have never 
been used and contain zeroes. 
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VOLUME DIRECTORY HEADER | 


SF Indicates Volume Directory Header Entry Follows 


| | 


‘e Name Is 7 Characters Long 


|_POINTER FIELDS | 


Next DIR | Ong > Volume Name Is EXAMPLE 
Block Is3 


i H Minimum ae 
j Versions = 0 a 
OIR Block. Ss \. i Volume DIR Access 


No Previous 
‘ _-SC3 = DESTROY /RENAME 
ee WRITE /READ Enabled 









ve ~ $118 +280} Blocks on Volume Total 
ify 
Hl 






3 Files in This 
OR 


ee, 








06 seogeagiaepeogeeina a 
VOL Creation ToC ooognoegaaads BOOGMORGOG00 risa ee 
Date (not set) 3 Sedo oaquoadsd Th: set — Entry Lengths $27 Bytes i 


























“ENTRIES PER BLOCK — —>4 aie 
s SD wire saeneceuaacutentreice ~BAS File Type 
facie: = yeeae 076001 0U8G00UGG00000GU000 ............ 
in Block 6 ~ 48 GYE3G19800G0G00002001754 .C.......-- T $1 Indicates Seedling File 
54° 585446494C45000800000000 XTFILE-~++=s"~ ~ S7Characters inName 
TXT FileType = # GHA 4] GGG 1 VORABESGHTUT ............ uw. -Key Block = $9 
6C 0006 E349069000 A -1 Block sn Fate 
78 Eu 60 . (BINFILE! . .----——Fite Name 
[3006 ee — ~ End of File at $30 





Date F-le Last Modified (not 
set) 





~~ =~ AUX_TYPE—For BIN 
File AS300 


For This File ‘Remaindes of Biock Zeroesi 


“Recess SE3 = DESTROY ‘RENAME Enabled 
Backup Needed 
WRITE /READ Enabled 


Ong /Manimum Version of File = 0 


Figure 46 Example Volume Directory Block 


FILE STRUCTURES 


One of ProDOS’s major jobs is to keep track of the blocks which 
make up a file. When programming, the user need never know that 
a file is actually made up of one or more blocks scattered far and 
wide all over the diskette volume. ProDOS must make the file 
appear to the programmer to be a continuous stream of sequential 
data. 

So far the files shown in the examples here have had only one 
block. This was done to avoid complicating the discussion of the 
Volume Directory. In practice, however, very few files are 512 
bytes or less in length. ProDOS defines three file structures to 
handle files of different sizes: 


The Seedling — for files of 512 bytes or less 

The Sapling —for files with more than 512 bytes but 
less than 128K bytes of data 

The Tree —for files with more than 128K bytes of 
data up to 16 megabytes (16,777,216 
bytes). 
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Examples of seedling files have already been shown. A seedling 
file consists of a single data block whose number is stored in the 
KEY_POINTER field in the file entry of the directory. Thus, a 
seedling file, by definition, costs only one block of storage (and a 
file descriptive entry). 

For the purposes of this discussion, let us assume that we had 
run the following Applesoft BASIC program against our example 
disk volume from Figure 4.2. 


1@ PRINT CHRS$(4);"OPEN TXTFILE,L64" 
2@ FOR I=6 TO 2 

3@ PRINT CHRS$(4);"WRITE TXTFILE,R";1I 
48 PRINT "RECORD"; 1 

58 NEXT I 

6@ PRINT CHRS$(4);"CLOSE TXTFILE" 

76 END 


This program creates the TXT file, “TXTFILE”, with a record 
length of 64 bytes. It then writes three records containing the 
strings “RECORDO”, “RECORD1”, and “RECORD2”. The total 
size of this file is then 3 times 64 or 192 bytes. Since this is less than 
512 bytes, the file is stored as a seedling. 

Now, assume that statement 20 is changed to read: 


26 FOR I=@ TO 186 
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and the program is rerun. The file it creates will now contain 101 
records of 64 bytes each, so the total size is 6464 bytes. As the ninth 
record is written (RECORD8), ProDOS discovers that the original 
seedling block is full. There is no room in the directory to store 
another block number, so ProDOS creates what is called an index 
block. This block contains the block numbers of each data block in 
the file in the order that they should be accessed. Using an index 
block, ProDOS can describe the file in a sequential and orderly 
way, even though its data blocks may not be physically contiguous 
(next to one another on the diskette). For example, if the previous 
data block in a file was 47, it is not necessary to store the data 
which follows it in block 48. Instead, any free block located any- 
where on the diskette may be used simply by placing its block 
number next to 47’s in the index block. 

Thus, in our example, a new block is allocated to be the index 
block ($A), another new block is allocated to be the second data 
block ($B), both the original data block’s number and the new data 
block’s number are placed in the new index block, and, finally, the 
directory entry for the file is updated so that it now points to the 
index block instead of the seedling data block. Of course, the 
STORAGE_TYPE field in the directory entry must also be 
changed to indicate that this is now a sapling file and is no longer a 
seedling. Index block entries which are not associated with any 
data block yet (such as those beyond the end of file position) are set 
to zeroes. Since a block is 512 bytes long and block numbers 
require a 2-byte field, this index block can store pointers to up to 
256 data blocks representing up to 131,072 bytes of data (128K). 
Obviously, most files will fall within this class of file structure. A 
diagram of the general form of a sapling file is given in Figure 4:7. 


DIRECTORY ENTRY INDEX BLOCK 













“IXTFILE 














XT TO 
SECOND BLOCK THIRO BLOCK \ Pf BLOCK LAST BLOCK 
OF “IXTFILE” OF 'TXTFHE «=| = =°°ee® OF TXTFILE OF “TXTFILE 


Figure 4.7 Sapling File Organization 


FIRST BLOCK 
OF “TXTFILE™ 
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The index block for TXTFILE is given in Figure 4.8. Notice that 
the first block of the file is still block 8, the original data block of 
the old seedling version of TXTFILE. Notice also that in an index 
block, the least significant byte of the block numbers are stored in 
the first half of the block, and the most significant byte (in this 
example all MSB’s are $00) in the last half. This was done to sim- 
plify indexing into the block (the 6502 index registers can only 
index up to 256 bytes at a time). Thus, to find any given block, one 


BLOCK $A 


980 





oac [16 


018 
924 
030 
@3C 
@48 
@54 


FIRST ee 
HALF OF 

INDEX oi 
BLOCK 


(LSBs) ae 


@A8 
OB4 
@ce 
gcc 
gD8 
OE4 
GFG 
BFC 
188 
1ac 
118 
124 
138 
13c 


SECOND es ‘ 

HALF OF 

INDEX tee 

BLOCK 18 

(MSBs) 184 
196 
19C¢ 
1A8 
1B4 
1c@ 
1cc 
1D8 
1E4 
1F@ 
1FC 








$0008 First data 
GAASOAGGGGGGGTGGIGGTBARG ......-....4. j block of file is 


BAASSSOSCESUGGBOGGGCGGGGI~....-..- 2s Block $8 
OOBOSSBASSASGAGSGOLGLGHGGS .. rr. -- eee 
GOSSOSSOCAGADGAGGGOAGGGG .....N..e-- 
BOSSOACCCAGASASSGGGEBGAG .....---s Rehaia 
SOSSIBSSSSSSASBGGSGSGGSS .. 1.2... eR 
OCOGEBGAASGAGBGGGIGAGGGG .......-.. 
OCOCBGGGOCCBAAGGUGGGIGGIGG ......-.. Cas. OM ‘ 
OGESOSICOACSOABGIGUGGAGS .....,0%..-- A 
OOOOSSSGCASIGEGBOGBSGGGD ...n7.....-- \ 
GOGCOGGIGOSSGGABGAGGRG0G —.........--- -\ 
GYUCSOBGGESOAGGBGGGGOBEHS ..........-. 7 
GADGASOGCCGGGGGAZETGGBGGG .....-- cee ee $0016 Last data 


OGGGGdGGRGGRR000R0000000 ............ {file 
G0000609G00000000000000G ............ ) block of file is 
















0800G900000000G000000000 ............ Block $16 
88900000 oes 
(OGl0GvOGGGGER0G00GG000000 ............ / 
jadlasausaeogeaeaogogao0ge . eo 
GBGSTSOUBOSSSGSAGGGGGGGG ...,..4<77.... 
60G900000G000000GG000000 ............ 
G@GGGGGGOCOGGGGGABGGGOOKG ............ 
BAGOOPCGGOGUGGOGGUGGGOGG ...........- 
GGOGGUGABGGCGOCOGGGGGGGG ............ 
8GGG0G0G0000000000000008 ............ 
800000000000000G00000008 ............ 
606000000000G00000000000 ............ 
-608G000G0000GG0000000009 ..........-. 
806900000000000000000GG0 ... 
GGG9GGR000GG0G00000G00R0 . 
600000606000000000000000 
89GGG0GGGGGRR0RGG0GR0000 
800G0000000G008000000086 
800000606060000G000G0000 
000000000G00000000000000 
000000000000G00000000000 
68808G0000000000000000G0 
63OGGGG00GR00G00000000R0 
96900009 ateas 









Figure 4.8 Example Sapling Index Block 
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must assemble a block number by picking the Nth byte and the N 
+ 256th byte in the index block where N is the relative block 
desired. 

Suppose that we now modify our program again so that 2144 
records will be written. This pushes the total file size up to 137,216, 
more than can be described by a single index block. ProDOS must 
“promote” the file to the next level of the hierarchy, a tree file. A 
tree file consists of a single master index block, pointed to by the 
directory entry, which, in turn, contains the block numbers of two 
or more other index blocks. These lower level index blocks contain 
the actual data block numbers. This structure is diagrammed in 
Figure 4.9. Thus, since the master index block can describe 256 
“subindex” blocks, and each subindex block ean describe 256 data 
blocks, in principle this structure would support files of up to 32 
megabytes! In order to limit block numbers to a 2-byte signed 
value of 32767, however, an arbitrary upper limit of 16 megabytes 
was imposed. In other words, a master index block can never be 
more than half full. 

The entire file structure for TXTFILE is depicted in Figure 
4,10. Note that the original index block of the sapling file (block 
$A) became the first subindex block of the tree file. Also, when the 
changeover was made, the master index block was allocated first 


DIRECTORY ENTRY 


MASTER 
~TXTFILE INDEX BLOCK 







LAST 
(INDEX BLOCK 












256TH BLOCK 
OF “TXTFILE 





257TH BLOCK 
OF “TXTFILE 


LAST BLOCK 
OF “TXTFILE™ 


FIRST Bl OCK SECOND BLOCK | |... 
OF “TXTFILE OF “TXTFILE 


Figure 49 Tree File Organization 








BLOCK $010A 


BLOCK $000A 





WBOCEDOEOF1YL1LI2121415 
ISLI9JIALBICIDILIF2G21 
2526272€292A2B2C 2D 
2ZE2EF 301323334 3536373839 
3A3B IC IRIEIF4G4142434445 
464748498A4B4C4D4E6F5451 
$253545558575859SA5B5C5b 





BLOCK $0008 | 


52454 34F524430000UGueCoU 
909600800000 0000UGGG00HU 
BOSAGCOGUOVOOVUOUBGULUOU 
98800880000G08GU0 5000006 
@5G00G9GA0000G0G0CB08GK0" 
G060000052454 34F52443100 
680950000409 068805C00006 
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MASTER INDEX BLOCK 


8GG00008 





t 
INDEX BLOCK 0 BLOCK $0108 (INDEX BLOCK 1 


OCGDSESFLAI1121314151 627) 


“AS a&'() FAH 
~/8123456789 
23=>2@ABCOE 
FGHI JKLMNOPYQ 
RSTUVWXYZ[/] 


81616191912101 
838000009008008 
69808G900G8900 
SGeIEGGoaa0IsE 
9868669889000: 
6888808GG080G8 
68685808080800 





eggegoeed 
G90h00GR0 
962000008 
agegsaaee 
669630000 





BLOCK $0117 \ 


5245434F5244 323135360006 
6899085880000 8R9ECVO0006 
BOCELGOVGHEUHOBOLDOHUUUOE 
GOOSESOOVGBUGBYVOBULOHUOD 
PVBBOCVGGHHUGBOHVCUCOVOUH 
0000608052454 34652443231 
33379DGORGHVOEBVBEBLOUOO 37., 


DATA BLOCK 0 
RECORDG.. 


DATA BLOCK 267 
RECORD21 36.4, 


+ RECORD). 





Figure 4.40 Example Tree File 
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($10A), then the second subindex block ($10B), and finally the data 
block whose allocation made the file into a tree file ($10C). The last 
block allocated is for RECORD2136 through RECORD2143 (for a 
total of 2144 records). This is the last block on the diskette ($117), 
and, since no blocks were ever freed, the diskette is now full. 
Although TXTFILE has only two subindex blocks and it is nearly 
as large as a diskette, this does not imply that all tree files will 
have two subindex blocks, as will become apparent when sparse 
files are discussed. 


FILE DATA TYPES 


Unless they are directories (DIR type files), all files conform to 
one of the three file structures described above even though the 
data in files may have different intended uses. A file might contain 
an Applesoft BASIC program which was SAVEd in addition 
to being a sapling file. It might be a binary memory image which 
was BSAVEd and conforms to the seedling structure. Or it might 
be data for a BASIC program in a TXT file and have the tree 
characteristic. File types, such as BAS, TXT, or SYS are less 
important to ProDOS than they are to the programs which use the 
files. This means that the basic structure of a BAS file is identical 
to that of a BIN file—only the interpretation of the data differs. 
ProDOS maintains a consistent set of file types by convention, and 
toa limited extent, the BASIC command interpreter enforces these 
conventions (e.g., “FILE TYPE MISMATCH”). You are not pre- 
vented, however, from storing an Applesoft BASIC program 
image ina TXT file if you really work at it! 


TXT FILES 

The TXT or text file in its sequential form is the least compli- 
cated file data type (in its random form it is, perhaps, the most 
complex). A sequential TXT file consists of one or more records, 
separated from each other by carriage return characters (hex 
$0D’s). This structure is shown and an example file is given in 
Figure 4.11. Usually, the end of a TXT file is signaled by the End 
Of File (EOF) position stored in the directory entry for the file. 
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EOF 


RECORD 0 RECORD 1 RECORD 2 


A Sequential Text TXT Type File 


END OF FILE 
POSITION 


RECORD O 





\ SN 
@B_312C322C332C34ODBGGGG00G08 1,2,3,4,.... 
OC BOBGCOGGGBGSADGOSGGBGGGGG ....... ene 
18 GGCOBBGSOAGBGSGGGGAGGGGAG .........00 
24 GIBGGOSGOBISGGBGGGGGGGGG ........2nee 
38 GOOEOOGOSOOGBGGGGBGOGGGG ...........4. 
3C GOGGBABGGBAAGGGGGGOGGBGG .........2.4.% 
48 GOBGSGGGGCGGGGAGGGGGGOOGSG ..........4. 
54 O@GOGBOGCDGAGISGGAGGGAGGG ........2nee 

(Remainder of Block Zeroes) 





Figure 4.44 Example Sequential Text File Block 


Since $0D is used to delimit records, carriage returns should not 
appear within a record. Usually, only valid ASCII characters are 
allowed ina TXT file to make them accessible to BASIC programs 
(i.e. printable text, numerics or special characters; refer to p. 8 of 
the Apple IT Reference Manual or p. 16 of the Apple I] Reference 
Manual for Ile Only). This restriction makes processing of a TXT 
file slower and less efficient in the use of disk space than witha 
BIN or VAR type file, since each digit must occupy a full byte in 
the file. 

When TXT files are accessed randomly, or by record number, 
“holes” can appear between records. In the example given earlier 
and in Figure 4.12, each record is allotted 64 bytes of space in the 
file. By doing this, it is easy to find any record by multiplying its 
number by 64 and using this as a byte offset into the file. The 
record length is chosen as the maximum amount of space any 
record might occupy. Thus, records with less than 64 bytes of data, 
such as the ones in the example, will have wasted space at their end 
(filled, in this case, with $00s). This wasted space is called padding. 
The actual data in each record is terminated with a $0D (carriage 
return) just as in the sequential text file record (allowing BASIC to 
read it as a single INPUT line). In this way, data within a single 
record can be accessed as if it was a miniature sequential TXT file. 
If an attempt is made to sequentially read beyond into the padding, 
a null string is returned. 
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When the randomly organized file is OPENed, the record length 
given with the “L” keyword is stored in the AUX_TYPE field in 
the directory entry for the file. Then, if later OPENs omit this 
keyword, the original value can be supplied by ProDOS. 

Notice that in the example in Figure 4.12, record 3 has not been 
initialized. Indeed, none of the other records following RECORD2 
have anything but $00s in them. By WRITEing to specific records 
in a non-sequential order, it is possible to leave very large holes 
between records which contain data. Such files are called “sparse.” 
If a hole falls within a block which has other records which contain 
data, it is represented by binary zeroes. But if the hole covers entire 
blocks, ProDOS does not bother to allocate them at all. There is no 
point in wasting disk space on holes! Thus, if the next record con- 
taining data in our example file was RECORD25, for instance, the 


RECORD 0 RECORD 1 etc. 


a “~ 


A Random Text TXT Type File 


OATA (ch) _~ Padding to Make L64 
/ 7 ane 
@6 5245434F5244308D8DG000 RECORD@..... 


GC GGRGGGGGG00GR000R0RE0000 ............ westan 
18 GOGGGDGGGG0GGGGE00R0GG00 ............ ee 
24 GGggggeganGGgd0GeGGRG0GG ..........-. 6 
30 06900000000G00G00G0G0000 ............ 

a 3C_900000005245434F5244310D ....RECORD1. 
48 OGGOGGOGOCGGGOGGG0GG0GG0 ............ 
54 900G00000000000000000000 ............ 
60 0980000000G0000000G000G0 ............ 
6C 09G000800G0G000000000000 ............ 
78 9G00G0000000000005245434F ......-- RECO 
84 5244320D00008G0000000000G RD2........ . ) 
9G 890G0080000000G000G00G00 ............ RECORD 2 
9C 990000GG0000G00000GG00GG ............ | 64 BYTES 








RECORD 1 
64 BYTES 





AB GOSCGISOGGSSAGGOGAHSGGGOG .. 1... eee 
B4 GOGGGGGOSAGGGGGGOGGGGGGG ..........-- 
CO BAGSCAGCABGSSSACGOGGOGGG .... eee eeee NO DATA IN 


(Remainder of Block Zeroes) RECORD 3 


AUX_TYPE in directory contains record length = 64 





Figure 4.12 Example Random Text File Block 
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rest of block 0 would contain zeroes (as it does now), no block would 
be allocated for block 1 or block 2, and block 3 would contain zeroes 
until the position of RECORD25 was reached. This is diagrammed 
in Figure 4.13. Notice that the positions of the “phantom” blocks 
are marked in the file’s index block with zeroes. Thus, although the 
file covers a “data space” of six blocks, only three data blocks are 
actually allocated. It is possible to create a file with only two data 
blocks which covers the entire 16-megabyte data space. Such a file 
would incorporate one master index block with an entry at +0 and 
at+7F. All the subindex blocks in between would be “phantom,” or 
not allocated and marked with zero pointers. The first index bloek 
would contain a single entry at +0 for the first data block. And the 
last index block would contain a single entry at+FF for the last 
data block. A 16-megabyte file using only five blocks of disk space! 


BIN FILES 

The structure of a BIN type file is shown in Figure 4.14. An 
exact copy of the memory selected is written to the disk block(s). 
The original address from which the memory was copied is stored 
in the AUX_TYPE field of the directory entry for the file. The 
EOF position in the directory records the length of the binary 
image. These values are those given in the A and L (or E) keywords 
of the BSAVE command which created the file. ProDOS can be 
made to BLOAD or BRUN the binary image at a different address 
by specifying the A (address) keyword when the command is 
entered, or by changing the address in the directory entry (this is 
sometimes necessary if the file cannot be BSAVEd from the loca- 
tion where it will run, such as from the screen buffer). 


INDEX BLOCK 






BLOCK 0 OF BLOCK 5 OF 
FILE ILE FILE 


Figure 4.143 ASparse File 
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MEMORY IMAGE... 


A Binary BIN Type File 


$30 Byte Binary Memory Image 


08 4COGBE4SCOOBEGOOOGFFFFOGOGG L.>L.>.. 
OC FFFFOOOOFFFFOOGOFFFFOGGD 


N 
Vee 





18 FFFFOQOGFFFFOOGOS9FAQOBE .._..¥ 

24 1B4CG3BE4CGOBE4C59FFEBBF 3b.>L.>LY_K? aeneniel 
30 000000000000000000000000 ............ ae 
3C G08GG0000000000000000000 ............ 


48 GOCCCDOAOGHGGGOGGGOGGGGHGG .......2-0ee 
54 OGOGAAAGGOSCSTSGAGGGGGGG ........20- 
68 BAECOBAACOSSSSGGGAGGGGAG .........--. 
6C SOGGASGGGACAGGGGGAGGAGGG .......22 ee 
78 GOGCDBSGCGSGGUGGGOAGDGGBG ...... sence 
84 BGOGGBOSGVGOATAGSAGGGGGGG 1... eeeese 


(Remainder of Block Zeroes) 


AUX_TYPE in Directory Contains Address = $3D0 
EOF in Directory Contains Length = $30 
Figure 4.14 Example BIN File Block 


BAS FILES 

A BASIC program is saved to the diskette in a way that is nearly 
identical to BSAVE. The format of a BAS file is given in Figure 
4.15. When the SAVE command is typed, the ProDOS BASIC 
command interpreter determines the location of the BASIC pro- 
gram in memory and its length by examining Applesoft’s zero 
page addresses. An image of the program is written to the file and, 
again, the AUX_TYPE and EOF fields of the directory entry 
represent the address and length. Notice that the character repre- 
sentation of the program is somewhat garbled. This is because, in 
the interest of saving memory, BASIC “tokenizes” the program. 
Reserved BASIC words, such as PRINT, IF, END, or CHR$, are 
replaced with a single hexadecimal code value (set off from other 
characters by its most significant bit being forced on). A complete 
treatment of the appearance of a BASIC program in memory is 
outside of the scope of this manual, but-a partial breakdown of the 
program in Figure 4.15 is given. 
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PROGRAM MEMORY IMAGE... 


An Applesoft BAS Type File 


PRINT CHRS(4);"OPEN TXTFILE,L64" 
FOR I=@ TO 2 
PRINT CHRS(4);"WRITE TXTFILE,R";1 


PRINT “RECORD"; 1 











NEXT I 
PRINT CHRS(4);"CLOSE TXTFILE" 
END 
$BA = PRINT 
Address of Next 7=CH 4): "O...ete. 
Line=1 Line 10 Oe 
60 (LEGsgaaG E7128 34293B224F] ....:G(4) 3" 
OC S$0454E2G54585446494C452C PEN TXTFILE, 
18 4C36342280290814808149D8 L64".)....1P 
24 30C1320047081EG8BAE72834 GA2.G...:G6(4 
38 293B22575249544520545854 );"WRITE TXT Appiesoft 
3C 46494C452C52223B49005708 FILE,R”";1.W. Program Image 


48 2809BA225245434F5244223B (.:"RECORD"; 
54 49605E08320082496878G83C 1..2..1.X.< 
69 60BAE72834293B22434C4F53 .:G(4);"CLOS 
6C 452854585446494C4522607E E TXTFILE". 





EOF: Marks 78 @8460080000000GAD0000000 .F........-- 
End of Program 84 SGBGGGOGGGOGGTGGGGGOOGGG ............ 
Image 9G GAGAAGAGSGASSCAAGHGGGAGS .........20- 


9C BAOGOSGSSOBAOGGASGAGGGGGG ...........- 
AS SOBBOCCEGGGGGCAOGGGBGGGOGG ........44-. 
B4 OGGGOGOCGDGGGGGBGGGAGGGG .... cee eeee 
CB GOBGACEOBIGGGAGGAGGGGGGG .....-..-2e 


(Remainder of Block Zeroes) 


AUX.TYPE in Directory Contains Program Start Address = $801 
EOF in Directory Contains Program Length = $80 


Figure 4.15 Example BAS File Block 


OTHER FILE TYPES (VAR, REL, SYS) 


Several other file types have been set aside by ProDOS. Many 
are those found in the SOS operating system (e.g. PCD, PTX, PDA 
for Pascal, etc.). These are listed in APPENDIX E and will not be 
covered here since they are not indigenous to ProDOS. Other 
ProDOS file types include BAD and CMD. BAD files are obviously 
intended to mark permanent I/O errors on a disk’s surface from 
accidental use, but there seem to be no utilities within ProDOS 1.0 
which create them. The CMD and PAS file types are not currently 
supported by the ProDOS BASIC command interpreter, so their 
planned structures are anyone’s guess. AppleWorks file types are 
designed for the AppleWorks package, and their structures are 
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specific to that package. The formats of the VAR, REL, and SYS 
files are defined, however. 

The VAR file type is used to store the contents of a BASIC pro- 
gram’s variables using the STORE command. The ProDOS 
BASIC command interpreter compresses all of the strings 
together with the numeric variables and saves the resulting chunk 
of memory as a VAR file. The first five bytes of the file constitute a 
header which defines the memory image that follows: 


VAR FILE HEADER 


BYTE 
OFFSET | LENGTH | DESCRIPTION 


(2 bytes) | Combined length of simple and array 
variables. 


(2bytes) | Length of simple variables only. 

(1 byte) MSB of HIMEM when these variables 
were STOREd. 

(n bytes) |Start of memory image.... 





The AUX_TYPE field of the directory entry for the file contains 
the starting address from which the compressed variables were 
copied. EOF is an indication of the end of the image. When a 
RESTORE is later issued, the memory image is reloaded, the 
strings are separated from the rest of the variables, and, if neces- 
sary, string pointers are adjusted based on the new HIMEM value. 

The REL file type is used with a special form of binary file, con- 
taining the memory image of a machine language program which 
may be relocated anywhere in memory based upon additional 
information stored with the image itself. Such a file is called a 
Relocatable Object Module file and is produced as output from the 
Apple Toolkit Assembler (EZ DASM). The format for this type of file 
is given in the documentation accompanying the assembler. 

A SYS, or system file, is just like a BIN file except that it nearly 
always loads at $2000 and implies a reload of the command inter- 
preter after it exits. SYS files are invoked with the “-”, or smart 
RUN command, from the BASIC command interpreter. The inter- 
preter closes all open files, frees all of the memory occupied by 
itself, and does a standard BRUN at $2000. 
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DIR FILES—PRODOS SUBDIRECTORIES 


Since the Volume Directory has room for just 51 entries, without 
subdirectories, you would be limited to 51 files per volume. This 
may not seem to be much of a hardship on a diskette (although it 
might, since DOS 3.3 allows 105), but on a hard disk with 5 million 
bytes or more this limit is unthinkable. In order to create a more 
dynamic and flexible structure, the user is permitted to create 
subdirectories. A subdirectory can be thought of as an extension 
to the Volume Directory, but there is more to it than that. In the 
simplest case, a subdirectory is created and an entry which de- 
scribes it is placed in the Volume Directory. The subdirectory has a 
structure very similar to the Volume Directory: it has a header 
entry located at its beginning; its blocks are doubly linked by point- 
ers in the first four bytes of each block; and it can contain file 
descriptive entries (including entries for “sub-subdirectories”). 
Unlike the Volume Directory, however, it can be of any length (it 
starts out with only a single block and more are added as 
required), its header has a slightly different format, it can be 
located anywhere on the diskette, and its blocks are not necessary 
contiguous. A diagram of a typical subdirectory is shown in Figure 
4.16. Thus, within a single subdirectory, you can create as many 
file entries as you have disk blocks! In, practice, however, it is usu- 
ally more convenient to create multiple subdirectories “dangling” 
from the Volume Directory, each for a specific purpose (e.g. one for 
word processing, one for program development, one for spread- 
sheets, and so on). These subdirectories might even be thought of as 
miniature “diskettes” within the larger volume. Although it is pos- 
sible to set up very complex structures using subdirectories (mul- 
tiple level tree-like networks), usually this is not very efficient or 
convenient and a single level (all subdirectories linked directly to 
the Volume Directory) works best. 


One of the major concepts around which ProDOS was designed 
is the notion of a path to a file. Ordinarily, if a file is described by 
the Volume Directory, this path is very simple. ProDOS merely 
looks up the file in the Volume Directory and that is that. If the file 
is described by a subdirectory, however, ProDOS insists upon 
knowing how to find the subdirectory. Of course, ProDOS could 
systematically search all subdirectories for the file and all subdi- 
rectories of the subdirectories, and so on, but this would be very 
time consuming (especially if you had mistyped the file name and 
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BLOCK 2 


VOLUME 
DIRECTORY 









OTHER FILES 
OR 





SUBDIRECTORIES 


Figure 4.146 AProDOS Subdirectory 


it didn’t really exist!). Since the user usually knows which subdi- 
rectory contains the file (and, perhaps, which subdirectory de- 
seribes that subdirectory, etc.) the practice is to tell ProDOS what 
path to follow to find a file. This is done by first specifying the 
volume to be searched, thereby naming the Volume Directory, fol- 
lowed by a list of all subdirectories which must be traversed to 
eventually find the file, and finally by the file name itself. For 
example, if in Figure 4.16 the volume name is “VOLUME” and the 
subdirectory name is “SUB” and the file described by the subdi- 
rectory is “FILE,” the path to find that file would be: 


/VOLUME/SUB/FILE 


If the file described by the Volume Directory in Figure 4.16 was 
also called “FILE” there would be no confusion at all, because its 
pathname would be unique: 


/VOLUME/FILE 
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This points out an additional advantage of subdirectories. It was 
mentioned earlier that they were like miniature “diskettes,” and, 
just like diskettes, there is no problem in using identical file names 
within different directories. 

To make specifying pathnames easier, the user can specify a 
default prefix to ProDOS. When a file name is given (without a 
leading “/” in its name) it is assumed to be an incomplete path- 
name. To complete it, ProDOS merely attaches the prefix to the 
beginning. Thus, if the current prefix is: 


/VOLUME/SUB/ 


And a reference was made to “FILE,” ProDOS would create the 
following fully qualified pathname: 


/VOLUME/SUB/FILE 


Therefore, by specifying a prefix you are, in a sense, stating that 
you wish to work within a specific “miniature diskette,” although 
you can still access any other file on the volume by giving its com- 
plete pathname explicitly. 

An example of a typical subdirectory block is given in Figure 
4.17, The format of the Subdirectory Header is given below 
(remember that the first four bytes of each subdirectory block con- 
tain the previous and next block numbers respectively): 





Byte [DESCRIPTION — 


$04 STORAGE_TY PE/NAME_LENGTH: The first nibble 
(top 4 bits) of this byte describes the type of entry. In this 
case, this is a Subdirectory Header so this nibble is $E. 
The low 4 bits are the length of the name in the next field 
(the subdirectory name). 

$05-$13 SUBDIR _NAME: A 15-byte field containing the name 
of this subdirectory. The actual length is defined by 
NAME_LENGTH above; the remainder of the field is 
ignored. 

$14 $14 must contain $75. 

$15-$1B Reserved for future use. 

$1C-$1F CREATION: The date and time of the creation of this 
subdirectory. This field is zero if no date was assigned. 
The format of the field is as follows: 


BYTE 0 and 1—yyyyyyymmmmddddd _ year/month/day 
BYTE 2 and 3— 000hhhhh0Ommmmmm hours/minutes 


Volumes, Directories, and Files 4-29 





Start off SUBDIRECTORY HEADER 


$E indicates Subdirectory 








Pointer Fields 
(no other blocks) 
8 Character DIR Name “SUBSTUFF” —_Creating/ Minimum 

ProDOS Versions 

7. ..HSUBSTU Access: $C3= 
usagevogsavaeaud7aasas Besss7..UHUS —DESTROY/ RENAME 


INE ....--C’ WRITE/READ Enabled 













BQ 

Creation ec 
Date/Time ___18 
(not set) 





Entry Length Is 


| es 















eel Y8G1GGGGGCBRGGG0G ............ S27 Bytes 
; “a GO13¢6 
Ble ont G3GGaGGQaa 
(1 File) dascoeaousua 
4 eoeasgae AGSSCSAGGGGHR .... ew eeee 
Parent DIR 
Starts in Block 2 4GOGGG0GG0R0 
(VOL DIR) 84 HOGEGEGGIGABSGGAGGGGGGGAG \N... ew eeee 
(Remainder of Block Zeroes) 
Parent Entry # 
(5th Entry is For “AFILE™ 
Describes This Parent Entry Seedling 
Subdirectory) Length ts 27 Type = BIN 
Bytes Data Block = $114 
EOF = $100 
Full Access 
AUX_TYPE = A$800 


OIR Header in Block $113 


Figure 4.17 Example Subdirectory Block 


where each letter above represents one binary bit. This 
is the standard form for all create and modify date/time 
stamps in directories. 

$20 VERSION: The ProDOS version number under which 
this subdirectory was created. This field tells later ver- 
sions of ProDOS not to expect to find any fields which 
were defined by Apple after this version of ProDOS was 
released. This field indicates the level of upward com- 
patibility between versions. Under ProDOS 1.0, its 
value is zero. 

$21 MIN_VERSION: Minimum version of ProDOS which 
can access this subdirectory. A value in this field implies 
that significant changes were made to the field defini- 
tions since prior versions of ProDOS were in use and 
these older versions would not be able to successfully 
interpret the structure of this subdirectory. This field 
indicates the level of downward compatibility between 
versions. Under ProDOS 1.0, its value is zero. 
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$22 ACCESS: The bits in the flag byte define how the direc- 
tory may be accessed. The bit assignments are as 
follows: 


$80 —Subdirectory may be destroyed (deleted) 
$40 — Subdirectory may be renamed 

$20 —Subdirectory has changed since last backup 
$02 — Subdirectory may be written to 

$01 — Subdirectory may be read 


All other bits are reserved for future use. 

$23 ENTRY_LENGTH: Length of each entry in the Subdi- 
rectory in bytes (usually $27). 

$24 ENTRIES_PER_BLOCK: Number of entries in each 
block of the Subdirectory (usually $0D). Note that the 
Subdirectory Header is considered to be an entry. 

$25-$26 FILE COUNT: Number of active entries in the Subdi- 
rectory. An active entry is one which describes a file or 
subdirectory which has not been deleted. This count does 
not include the Subdirectory Header. Note that this 
field’s name is a bit misleading since the count also 
includes other subdirectory entries. 

$27-$28 PARENT_POINTER: The block number of the key 
(first) block of the directory which contains the entry 
which describes this subdirectory. 

$29 PARENT_ENTRY: The entry number within the par- 
ent directory which describes this subdirectory (the 
parent directory’s header counts as zero). 

$2A PARENT_ENTRY_LENGTH: The length of entries in 
the parent directory in bytes (usually $27). 


EMERGENCY REPAIRS 


From time to time the information on a diskette can become 
damaged or lost. This can create various symptoms, ranging from 
mild side effects, such as the disk not booting, to major problems, 
such as an input/output (I/O) error in the Volume Directory. A 
good understanding of the format of a diskette, as described pre- 
viously, and a few program tools can allow any reasonably sharp 
Apple II user to patch up most errors on his diskettes. 

A first question would be, “how do errors occur?” The most 
common cause of an error is a worn or physically damaged 
diskette. Usually a diskette will warn you that it is wearing out by 
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EMERGENCY REPAIRS ARE EASIER IF YOU HAVE A BACKUP 


producing “soft errors.” Soft errors are I/O errors which occur 
randomly. You may get an I/O error message when you CATALOG 
a disk one time and have it CATALOG correctly if you try again. 
When this happens, the smart programmer immediately copies 
the files on the aged diskette to a brand new one and discards the 
old one or keeps it as a backup. 

Another cause of damaged diskettes is the practice of hitting the 
RESET key to abort the execution of a program which is accessing 
the diskette. Damage will usually occur when the RESET signal. 
comes just as data is being written onto the disk. Powering the 
machine off just as data is being written to the disk is also a sure 
way to clobber a diskette. Of course, real hardware problems in the 
disk drive, cable, or controller card can cause damage as well. 

If the damaged diskette can be CATALOGed, recovery is much 
easier. A damaged ProDOS bootstrap loader on track 0 can usually 
be corrected by formatting a fresh diskette and copying the files 
from the old one to the new one. If only one file produces an I/O 
ERROR when it is used, it may be possible to copy most of the sec- 
tors of the file to another diskette by skipping over the bad sector 
with an assembler language program which calls the MLI 
(Machine Language Interface) in the ProDOS Kernel, or witha 
BASIC program (if the file is a TXT file). Indeed, if.the problem is 
a bad checksum (see Chapter 3), it may be possible to read the bad 
sector and ignore the error and get most of the data. 
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An I/O error usually means that one of two conditions has 
occurred. Either a bad checksum was detected on the data in a see- 
tor, meaning that all bytes in the sector which follow the point of 
damage may be lost; or the sectoring is clobbered such that the sec- 
tor no longer even exists on the diskette. If the latter is the case, the 
diskette (or at the very least, the track) must be reformatted, 
resulting in a massive loss of data. Although a program can be 
written to format a single track (see APPENDIX A), it is usually 
easier to copy all readable sectors from the damaged diskette to 
another formatted diskette and then reconstruct the lost data 
there. 


Disk utilities, such as Quality Software’s Bag of Tricks, allow the 
user to read and display the contents of sectors or blocks. Bay of 
Tricks will also allow you to modify the sector data and rewrite it to 
the same or another diskette. If you do not have Bag of Tricks or 
another commercial disk utility, you can use the ZAP program in 
APPENDIX A of this book. The ZAP program will read any block 
of an unprotected disk into memory, allowing the user to examine 
it or modify the data and then, optionally, rewrite it to a disk. 
Using such a program is very important when learning about 
diskette formats and when fixing clobbered data. 


Using ZAP, a bad sector within a file can be localized by reading 
each block listed in the index blocks for that file. If the bad block is 
in a directory, the pointers of up to 13 files may be lost. When 
this occurs, a search of the diskette can be made to find “homeless” 
index blocks {ones which are not otherwise connected to the 
remaining good directory blocks in that and other directories). As 
these index blocks are found, new file descriptive entries can be 
made in the damaged sector which point to these blocks. Of course, 
it helps to know whether the lost files are seedlings, saplings or 
trees! When the entire Volume Directory is lost, this process can 
take hours, even with a good understanding of the format of Pro- 
DOS volumes. Such an endeavor should only be undertaken if 
there is no other way to recover the data. Of course, the best policy 
is to create backup copies of important files periodically to sim- 
plify recovery. More information on the above procedures 1s given 
in APPENDIX A. 


A less significant but very annoying form of diskette clobber is 
the loss of free blocks. It is possible, by powering off or hitting 
RESET at the wrong time, to leave blocks marked in use in the 
Volume Bit Map which were about to be marked free. These lost 
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blocks can never be recovered by normal means, even when files 
are deleted, since they do not belong to anyone. The result is a 
DISK FULL message before the volume is actually full. To reclaim 
the lost block, it is necessary to compare every block listed in every 
index block or directory against the Volume Bit Map to see if there 
are any discrepancies. There are utility programs which will do 
this automatically, but the best way to solve this problem is to copy 
all the files on the diskette to another diskette (note that the 
diskette must be copied on a file by file basis, not as a volume, since 
a volume copy would copy an image of the diskette, bad Volume Bit 
Map and all). 


If a file is deleted it can usually be recovered, providing that 
additional block allocations have not occurred since it was deleted. 
If another file was created after the DELETE command, ProDOS 
probably has reused some or all of the blocks of the old file. The 
appropriate directory can be quickly ZAPped to reactivate the file 
(you will have to guess at the STORAGE_TYPE and 
NAME_LENGTH values) at +0 in the deleted entry. The file 
should then be copied to another disk and then the original deleted 
so that the Volume Bit Map will be correct. 


FRAGMENTATION 


ProDOS overhead in reading or writing blocks to a volume con- 
sists of three main parts: 


1. ProDOS computational overhead time (the time to get ready to 
access the disk). 

2. Seek time (moving the disk arm to the proper track). 

3. Rotational delay (waiting for the proper sector to appear under 
the disk head). 


In the first respect, ProDOS is an enormous improvement over 
Apple’s earlier operating system, DOS, being up to eight times 
faster in its operation. This fact only increases the significance of 
the other two delay areas. Skewing can have an effect on rotational 
delay to some extent (see Chapter 3), but is much more difficult to 
control. Seek time, however, can vary greatly depending upon use 
patterns and the arrangement of files on a volume. 

Imagine, for example, a volume on which a great deal of activity 


has occurred. Many files have been created and deleted over a 
period of time, leaving “holes” here and there as files are deleted, 
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which are reallocated to existing or new files as necessary. Even- 
tually, a map of the volume looks like a plate of spaghetti! There is 
nothing really wrong with this — files can be accessed normally — 
but if parts of an otherwise short file are spread all over the disk 
volume, ProDOS must spend a lot of time moving the disk read/ 
write head from track to track to pick up all the pieces in the 
proper order. This costs time. A disk volume in this state of affairs 
is said to be badly “fragmented.” Fragmentation can be even more 
important on a hard disk since the ratio of seek delay to rotational 
delay is much greater. Likewise, the best skewing setup in the 
world can be completely gutted by a fragmented disk, since few 
sequential file sectors are found together on the same track, and as 
the arm is moved to a new track there is no telling how long the 
rotational delay will be. 

When disk access time becomes a concern, it is sometimes useful 
to intelligently move files to specific spots on the disk. To accom- 
plish this, the user must format a new, blank volume and copy the 
files from the old disk, one by one, to the new disk in an appro- 
priate order. Remember that ProDOS allocates blocks for files in 
numerically increasing order (from the outside track of the disk to 
the inside track). Thus, the first file you copy will be placed near 
the Volume Directory (a good place to be if you want to find that 
file fast). The last file you copy will go closest to the center hub of 
the diskette. If your program accesses two files at once, try to place 
them near one another on the disk. Do not separate them by many 
other files or you will hear the disk arm “thrashing” back and forth: 
as it first accesses a block in file A and then must access one in file 
B. While you hear that noise, your program is not doing anything 
useful! Another thing to remember if your program opens and 
closes files frequently is that, when it does so, it may access several 
directories. It is usually a good idea in any case to keep all of your 
directories squashed down against the Volume Directory (i.e. 
CREATE all directories before you copy any files onto the new 
diskette) so that pathname searches will go faster. 


CHAPTER 5 


THE STRUCTURE OF PRODOS 


ProDOS MEMORY USE 


ProDOS is an assembly language program which is loaded into 
RAM memory when the user boots his disk. Although the ProDOS 
machine language support routines can run by themselves ina 
machine smaller than 64K (or 48K plus a language card), ProDOS 
is primarily intended to run only ona full sized 64K or larger 
Apple II Plus or an Apple Ie or IIc. Ina 64K Apple II, ProDOS 
normally occupies the 16K of bank switched memory (or the 
Language Card for older Apples) and about 10.5K at the top of 
main memory ($9600 through $BF FF). The part of ProDOS which 
occupies the bank switched memory is called the Kernel. The part 
occupying the top of main memory is called the BASIC 
Interpreter (BI). The Kernel consists of support subroutines 
which may be called by any assembly language program (such as 
the BASIC Interpreter) to access the disk, either block by block or 
file by file. The BASIC Interpreter accepts ProDOS commands 
entered by the user or his programs, and translates them into calls 
to the Kernel subroutines.* When the BASIC Interpreter is loaded, 
ProDOS must fool Applesoft BASIC into believing that there is 


*It is possible, if the BASIC Interpreter’s functions are not required by an 
application (such as a stand alone arcade-type game), to separate the Kernel from 
the BASIC Interpreter and not even load the BASIC Interpreter. For the purposes 
of this discussion, however, we will assume that ProDOS consists of both the Kernel 
and the BASIC Interpreter. In addition, the ProDOS Kernel may be loaded into the 
main part of memory if the Apple does not have a language card (48K Apple IT), but 
the BASIC Interpreter may not be used under these circumstances because it 
cannot be relocated. 
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actually less RAM memory in the machine than there is. With 
ProDOS loaded, Applesoft believes that there is only about 38K of 
RAM. ProDOS does this by adjusting HIMEM after it has loaded 
the BASIC Interpreter to prevent Applesoft from using the 
memory ProDOS is occupying. In order to keep track of the 
memory it is using, ProDOS maintains a “bit map” table which 
describes every page (256 bytes) in memory and marks it either 
free or in-use. By examining this table, user written programs can 
avoid using previously assigned memory, even if later versions of 
ProDOS are loaded elsewhere. 

A diagram of ProDOS’s memory is given in Figure 5.1. As can 
be seen, there are numerous subdivisions of the two basic 
components mentioned above. In addition, there are two special 
global pages containing addresses and data pertaining to the 
ProDOS Kernel (SYSTEM GLOBAL PAGE at $BF00) and the 
BASIC Interpreter (BI GLOBAL PAGE at $BE00) which may be 
of interest to external user written programs. These global pages 
will be discussed in more detail later in this chapter. 
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Figure 5.4 ProDOS Memory Usage (64K) 
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As discussed earlier, ProDOS can be divided into two major 
components: the Kernel, containing the Machine Language 
Interface (MLI); and the BASIC Interpreter (BI). In theory, other 
interpreters could be written and substituted for the BI (to support 
Pascal or C language development, for example) but at present the 
only interpreter provided by Apple is the BASIC Interpreter, 
supporting Applesoft BASIC. There is currently no support for the 
older Integer BASIC language. In fact, because of the memory 
utilization of ProDOS, Applesoft must be resident in ROM (since 
the Kernel resides in the language card). Hence, ProDOS is only 
supported for Apple II Pluses, IIe’s, and Ile’s. Use of the term 
“BASIC Interpreter” should not be confused with the Applesoft 
BASIC Interpreter in ROM.* Here, “interpreter” means 
“interpreter of disk access commands,” and not “interpreter of 
BASIC language statements.” Although the BI is closely 
“married” to the Applesoft interpreter in ROM, its primary 
responsibility is to interpret ProDOS commands which load and 
save files, display directories, and support file operations in 
BASIC programs. 

The BI normally occupies memory from $9600 to $BEFF. The 
first 1K ($9600-$9.A00) is a general purpose buffer, used during 
Applesoft string garbage collection and for other purposes. 
Following this, at $9A00, are the actual machine language 
instructions and work areas of the BI. Any data which is 
considered to be of interest to external programs is placed in the 
BI Global Page at $BE00. As files are opened by BASIC programs, 
1024-byte file buffers are allocated and inserted between the 
general purpose buffer and the BI itself. To do this, the BI must 
relocate the general purpose buffer and any strings which were 
allocated by the running BASIC program lower in memory to 
make room for the file buffers. HIMEM must be lowered 
accordingly. Thus, the memory available to the BASIC program 
fluctuates according to the number of open files. 

The ProDOS Kernel occupies 12K of the 16K bank switched 
memory (language card). Most of the remaining 4K bank is not 
currently used, but is reserved by Apple for future use (the QUIT 
code occupies three pages currently). The main part of the ProDOS 


*Apple’s documentation also refers to the BASIC Interpreter as the “BASIC 
System Program.” “BASIC Interpreter” is used here because of frequent 
references to the “BI,” an earlier designation. 
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Kernel begins at $D000, and contains the Machine Language 
Interface (MLI) subroutines which allow access to the disk by 
other programs (such as the BI or user written machine language 
programs). MLI functions provided include: open a-file, create a 
new file, delete a file, rename a file, determine online volumes, 
read/write toa file, etc. The Kernel also handles interrupts for 
devices which can generate them. Access to these subroutines and 
their data is strictly controlled by the System Global Page which 
will be described next. Following the Kernel and its scratch space 
(work areas), isa 2K area devoted to device drivers. In order to 
provide a device independent interface to peripherals, subroutines 
are loaded here which can perform block oriented I/O to the Apple 
diskette drive, the /RAM “electronic” 64K memory diskette drive 
implemented in the Extended 80-Column Text card, and the 
Thunderclock. Additional device drivers (Hard disk, printer, etc.) 
must be placed in interface card ROM or in main RAM memory. 
The entry point addresses of each device driver in use are kept in 
the System Global Page. 


GLOBAL PAGES 


The System and BI Global Pages are maintained by ProDOS at 
fixed locations in main memory ($BF00 and $BE00 respectively). 
This practice allows important ProDOS data and subroutines to be 
accessed by external programs via a fixed location. Each time 
Apple makes a change in ProDOS and reassembles its source code, 
the addresses of all of the subroutines and variables may change. 
By putting the addresses of these routines and the variables 
themselves in fixed locations in memory, dependencies by a user 
written program on a particular version of ProDOS can be 
eliminated. Hopefully, all subroutines or data of general interest 
have been “vectored” through these global pages. If not, the 
programmer cannot be sure that a subroutine he calls directly will 
not “move out from under him” in a later version. 

The exact format of the System Global Page is given in Chapter 
8 but it contains the following information: 


1. JMP (Goto) instructions to the main entry of the MLI, a quit 
vector, a clock/calendar subroutine, ete. 

2. Addresses of the device drivers for each slot and drive. 

3. A list of all disk drives online, and the slot and drive each 
occupies. 
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The BI global page contains: 
1. 


co 0-4] 


. 1/0 vectors for PR# and IN# for 


. Default slot and drive. 
. BI status flags indicating whether 


. A “bit map” showing which pages of memory are in use and 


which are free. 


. Addresses of the buffers being used by MLI opened files. 
. Addresses of up to four interrupt handling routines and 


associated register save areas. 


. Current date, time and file level. 
. Amachine ID flag byte giving the model (e.g. Apple Ile) and 


memory in the machine on which ProDOS is currently 
running. 


. Various flags indicating MLI status and whether a card 


occupies any slot. 


. Language card bank switching routines. 
. Interrupt entry and exit routines. 
. ProDOS version number. 


Addresses of routines in the BI 
which allow warmstart, command 
scanning, and error message 
printing. 


each slot, and the currently active 
input and output streams. 


an EXEC file is active,a BASIC 
program is running, a file is being 
read or written, etc. 





. Parameters that allow a user to 


pass an external command line to the BI. 


. A table indicating which commands allow which keyword 


parameters (e.g. OPEN does not allow the AD keyword but 
does allow the L keyword). 


. The current value for all keywords (A,B,E,L,S,D,etc.). 
. The address of the pathname buffers within the BI. 
. Asubroutine used by the BI to access the MLI. 
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10. Parameter lists used by the BI to access the MLI. 
11. Vectors to the BI’s buffer allocate and free subroutines. 
12. The current HIMEM MSB. 


In addition to the ProDOS vectors in the global pages, the 
Monitor ROM and Applesoft maintain additional vectors of 
general interest from $3F0 through $3FF. They are: 


LO/HI address of the routine which handles a BRK. 
machine language instruction. Supported by the Autostart 
and Apple Ile and IIc ROMs. Normally contains the 
address of.a Monitor ROM routine which prints the 
contents of the registers. 

LO/HI address of routine which wil] handle RESET for 
Autostart and Apple Ile ROM. Normally the BI restart 
address ($BE00) is stored here, but the user may change it 
if he wishes to handle RESET himself. 

Power-up byte. Contains a “funny complement” of the 
RESET address with an $A5. This scheme is used to 
determine if the machine was just powered up or if 
RESET was pressed. If a power-up occurred, the 
Autostart ROM or Apple IIe ROM ignores the address at 
$3F2 (since it has never been initialized), and attempts to 
boot a diskette. To prevent this from happening when you 
change $3F2 to handle your own RESETs, EOR (exclusive 
OR) the new value at $3F3 with an $A5 and store the result 
in the power-up byte. 

AJMP toa machine language routine which is to be called 
when the “&” feature is used in Applesoft. Initialized by 
ProDOS to point to the BI command scanner vector. 
AJMP toa machine language routine which is to be called 
when acontrol-Y is entered from the monitor. 

AJMP toa machine language routine which is to be called 
when a non-maskable interrupt (NMI) occurs. 

LO/HI address of ProDOS’s IRQ maskable interrupt 
handler dispatcher. If you wish to handle an IRQ interrupt, 
install an interrupt handler into ProDOS—do not replace 
this vector. 
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WHAT HAPPENS DURING BOOTING 


When an Apple is powered on, its memory is essentially devoid of 
any programs. In order to get ProDOS running, a diskette is 
“booted.” The term “boot” refers to the process of bootstrap loading 
ProDOS into RAM. Bootstrap loading involves a series of steps 
which load successively bigger pieces of a program until all of the 
program is in memory and running. In the case of ProDOS, 
bootstrapping occurs in two major stages, corresponding to the 
loading of the ProDOS Kernel and the BASIC Interpreter. Within 
these major stages, there are minor stages which must be 
- performed to complete the loading process. Figures 5.2 and 5.3 
: diagram the processes involved in loading the Kernel and the BI 
respectively from the diskette. A description of this process 
follows. 


The first boot stage is the execution of the ROM on the disk 
controller card. This is called the Boot ROM, and it exists on 
either the diskette controller card or a hard disk controller card at 


or 
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$Cs00 (where “s” is the slot number). Thus, when the Apple is first 
powered on, the Monitor ROM searches the slots for a disk 
controller card (starting with slot 7 and moving down in slot 
number) and, upon finding one, it branches to $Cs00 (usually 
$C600 if the controller is in slot 6). Control is also passed to this 
address should the user type PR#6 in BASIC or C600G or 6(ctrl)P 
in the monitor. The diskette controller Boot ROM is a machine 
language program of about 256 bytes in length. When executed, it 
“recalibrates” the diskette arm by pulling it back to track 0 (the 
“clacketty-clack” noise that is heard), and then reads sector 0 from 
track 0 into RAM memory at location $800. Once this sector has 
been read, the Boot ROM jumps (GOTO’s) to $801 which is the 
second stage boot, the ProDOS Loader. 


The ProDOS Loader occupies the first block on a ProDOS 
diskette (physical sectors 0 and 2). Since the Boot ROM has only 
loaded sector 0, the first task the ProDOS Loader must perform is 
to load the remaining sector of itself. It does this by calling the 
Boot ROM as asubroutine, loading it at $900. Having completed 
this, a portion of the Boot ROM is copied into a subroutine in the 
ProDOS Loader itself (this variable code is different for a diskette 
or a hard disk), and uses this to search the diskette’s Volume 
Directory for a system file with the name “PRODOS”. This file 
contains an image of the ProDOS Relocator, the BI Loader, and the 
ProDOS Kernel itself. If the file can be found, its contents are read 
into memory at $2000, and the ProDOS Loader jumps to the 
ProDOS Relocator at $2000. 


The ProDOS Relocator prints a copyright and version number 
on the screen, and then begins to examine the machine in use to 
find out its model. This is done by testing the Monitor ROM for 
special model-dependent indicators and by checking for language 
card memory. The ProDOS Relocator assembles the data it has 
collected into a byte of flags indicating whether the machine is an 
Apple II, Apple II Plus, Apple Ie, Apple IIc, or an Apple III in 
Apple IT emulation mode. It also indicates the amount of memory 
available. Once this has been established, the Kernel image is 
copied either to the bank switched memory (language card) if the 
machine has 64K or more, or to $9000 for a 48K Apple. If the 
machine has 128K, a/RAM drive is set up in the alternate 64K 
memory. The peripheral card configuration is also checked, and a 
table of occupied slots and interface card identifications is made. 
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Figure 5.2 ProDOS Kernel Bootstrap Process 


The initialization of the Kernel is completed by moving an image 
of the System Global Page to $BF00 and initializing it as 
necessary. The BI Loader image is then copied to $800 and control 
transfers there to begin booting the BI. 

The BI Loader searches the Volume Directory for the first 
system file it can find whose name ends with “.SYSTEM”. The file 
which is found will normally be BASIC.SYSTEM, but any other 
interpreter could be loaded in this way. Ifa file is found, its 
contents are loaded into memory at $2000 and control passes to the 
BI Relocator at $2000. 
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The BI Relocator copies the BI image to high memory ($9A00), 
sets up the BI Global Page at $BE00, and marks the pages 
occupied by these as “in-use” in the System Global Page’s memory 
bit map. The screen and keyboard vectors in zero page (CSWL/H 
and KSWL/H) are modified to cause immediate transfer of control 
to the relocator, and a jump to BASIC’s coldstart entry is executed. 
As soon as Applesoft has completed initialization, it prints a 
prompt character “]’. This causes contro! to transfer back into the 
BI Relocator. CSWL/H and KSWL/H are restored to their norma] 
settings, and initialization of the BI Global Page is completed. Ifa 
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“STARTUP?” file can be found in the Volume Directory, an initial 
command line of “-"STARTUP” is dummied up and, after 
completing the vectors in page 3 ($3F0 etc.), control transfers to 
the BI through its vector at $BE00. 

The various stages of the boot process are covered again in 
greater detail in the ProDOS Program Logic Supplement—see 
Chapter 8 for details. 


CHAPTER 6 


USING ProDOS FROM 
ASSEMBLY LANGUAGE 


CAVEAT 


This chapter is aimed at the advanced assembly language 
programmer who wishes to access the disk at any level. Access to: 
the disk by BASIC programs is well documented in the ProDOS 
manual, BASIC Programming With ProDOS. The material 
presented in this chapter may be beyond the comprehension (at 
least for the present) of a programmer who has never used 
assembly language. 

Access to a diskette from assembly language may be 
accomplished at four different levels: 


Level 0 Direct access of the diskette controller 
Level 1 Block access 

Level 2 Machine Language Interface (MLI) access 
Level 3 BI command access 


At the lowest level is direct access of the diskette controller. 
Here, data is accessed byte by byte. This may be required to 
implement diskette protection schemes or to perform low level 
diagnostic or correction of I/O errors. The next level of access is by 
ProDOS blocks (two sectors per block). This is done using the ap- 
propriate ProDOS device driver; in this case, the diskette device 
driver. Ata higher level still is the ProDOS Machine Language 
Interface (MLI). Here, data may be accessed on a file basis. 
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Finally, the highest level of access is through the ProDOS BASIC 
Interpreter. Here, entire ProDOS command lines may be executed 
to produce formatted directory listings and the like. A detailed 
description of the programming considerations at each of these 
levels follows. 


DIRECT USE OF THE DISKETTE DRIVE 


It is often desirable or necessary to access the Apple’s disk drives 
directly from assembly language, without the use of ProDOS. 
Applications which might use direct disk access range from a user 
written operating system to ProDOS-independent utility 
programs. Direct access is acomplished using 16 addresses that 
provide eight on/off switches which directly control the hardware. 
For information on the disk hardware, please refer to 
APPENDIX D. The device address assignments are given in 


Table 6.1. 
Q0 Phase 0 off Phase 0 on 
Ql Phase 1 off Phase 1 on 
Q2 Phase 2 off Phase 2 on 
Q3 Phase 3 off Phase 3 on 
Q4 Drive off Drive on 
Select drive 1 Select drive 2 
Shift data Load data 
i register 
Write 


TABLE 6.4 ProDOS Hardware Addresses 


“OFF” SWITCHES “ON” SWITCHES 


BASE BASE 
ADDRESS|FUNCTION | ADDRESS} FUNCTION 















The last two switches are difficult to explain in single phrase 
definitions because they interact with each other forming a 4-way 
switch. The four possible settings are given in Table 6.2. 
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TABLE 6.2 Four Way @6/Q7 Switches 


Qs |Q7|FUNCTION, 


Off | Off | Enable read sequencing. 
Off | On | Shift data register every four cycles 
while writing. 


On | Off | Check write protect and initialize 
sequencer for writing. 

On | On } Load data register every four cycles 
while writing. 





The addresses are slot dependent and the offsets are computed 
by multiplying the slot number by 16. In hexadecimal this works 
out nicely. Simply add the value $s0 (where s is the slot number) to 
the base address. To engage disk drive number 1 in slot number 6, 
for example, we would add $60 to $CO8A (device address 
assignment for engaging drive 1) for a result of $COEA. However, 
since it is generally desirable to write code that is not slot 
dependent, one would normally use $CO8A,X (where the X- 
register contains the value $s0). Table 6.3 shows the range of 
addresses for each slot number. 


TABLE 6.3 Address Ranges For Slots 


SLOT ADDRESS 

NUMBER RANGE 
$C080—$C08F 
$C090—$CO9F 
$COAO—$COAF 
$COBO—$COBF 
$COCO—$COCF 
$CODO—$CODF 
$COEO—$COEF 
$COFO—$COFF 
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In general, the above addresses need only be accessed with any 
valid 6502 instruction. However, in the case of reading and writing 
bytes (last four addresses), care must be taken to insure that the 
data wil] be in an appropriate register. All of the following would 
engage drive number 1. (Assume slot number 6.) 


BIT SC8EA 
LDA SCO8A,X (where X-register contains $66) 
CMP SCGO8A,X {where X-register contains $68) 


Below are typical examples demonstrating the use of-the device 
address assignments. For more examples, see APPENDIX A. All 
examples assume that the label SLOT is set to 16 times the desired 
slot number (e.g. $60 for slot 6). 


STEPPER PHASE OFF OR ON 

Basically, each of the four phases (0-3) must be turned on and 
then off again. Done in ascending order moves the arm inward. In 
descending order, the arm moves outward. For optimum 
performance, the timing between accesses-to these locations is 
critical, making this a nontrivial exercise. An example is provided 
in APPENDIX A demonstrating how to move the arm to a given 
location. 


MOTOR OFF OR ON 
LOX #SLOT Put slot number times 16 in X-register. 
LDA $C@88,X Turn motor off. 
LDX #SLOT Put slot number times 16 in X-register. 
LDA $C@89,X Turn motor on (selected drive). 


NOTE: A sufficient delay should be provided to allow the motor 
time to come up to speed before reading or writing to the 
disk. Either a specific delay or a routine that watches the 
data register can be used. See APPENDIX A for an 
example. 
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ENGAGE DRIVE 4 OR 2 
LDX #SLOT Put slot number times 16 in X-register. 
LDA $C@8A,X Engage drive l. 
LDX #SLOT Put slot number times 16 in X-register. 
LDA $C@8B,X Engage drive 2. 
LDX #SLOT Put slot number times 16 in X-register. 
LDA SC@8E,X Insure Read mode. 
READ LDA S$C@8C,X Put contents of data register in Accumulator. 
BPL READ Loop until the high bit is set. 


NOTE: $CO8E,X must be accessed to assure Read mode. The 
loop is necessary to assure that the accumulator will 
contain valid data. If the data register does not yet 
contain valid data, the high bit will be zero. 


SENSE WRITE PROTECT 
LDX #SLOT Put slot number times 16 in X-register. 
LDA $C@8D,xX 
LDA S$C@8E,X Sense write protect. 
BMI ERROR If high bit set, protected. 

WRITE LOAD AND WRITE A BYTE 
LDX #SLOT Put slot number times 16 in X-register. 
LDA DATA Load Accumulator with byte to write. 
STA $CO8D,X Write load. 
ORA $CO8C,X Write byte. 


NOTE: $CO8F,X must already have been accessed to insure 
Write mode and a 100-microsecond delay should be 
invoked before writing. 


6-6 Beneath Apple ProDOS 


Due to hardware constraints, norma] data bytes must be written 
in 32-eycle loops. The example below writes the two bytes $D5 and 
$AA to the disk. It does this by an immediate load of the 
accumulator, followed by a subroutine call (WRITE9) that writes 
the byte in the accumulator. Timing is so critical that different 
routines may be necessary, depending on how the data is to be 
accessed, and code cannot cross memory page boundaries without 
an adjustment. 


LDA #$D5 Load byte to write. (2 cycles) 

JSR WRITE9 Go write it. (6) 

LDA #SAA Load byte to write. (2) 

JSR WRITES Go write it. (6) 
WRITE9 CLC Provide different (2) 
WRITE? PHA delays to produce (3) 

PLA correct timing. (4) 
WRITE STA $C@8D,X Store byte in register. (5) 

ORA S$C88C,X Write byte. (4) 

RTS Return to caller. (6) 


CALLING A STORAGE DEVICE DRIVER (BLOCK ACCESS) 


ProDOS is device independent in that it requires a device 
driver for all storage devices. ProDOS comes with two device 
drivers built in. One supports the standard Apple floppy disk 
drive (Disk II or equivalent). The other supports a RAM drive on 
the Apple IIc or an Apple [Je that has 128K of memory. ProDOS 
can also support the ProFile hard disk which has its device driver 
on ROM. It seems clear that there will be many kinds of storage 
devices available in the future, each with its own driver. 

These device drivers are used as subroutines by the MLI and 
provide the means of accessing the appropriate device. Four basic 
functions are currently defined for a device driver. They are 
STATUS, READ, WRITE, and FORMAT. However, not all 
device drivers will provide all four functions. The Disk II Device 
Driver, for example, does not support FORMAT: because of space 
constraints, this function is provided in the program named 
FILER. 

The READ BLOCK and WRITE BLOCK ealls in the MLI 
provide the only means of using a device driver from ProDOS and 
is the preferred method. While it is not generally recommended, 
any device driver can be called directly. This could prove useful 
in particular applications that don’t require the MLI. Great care 
should be taken when calling the device driver directly because 
doing so can easily destroy data on the particular storage device. 
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While the parameters to call a device driver are quite 
straightforward, there are several potential difficulties to 
consider. First, RAM based device drivers normally reside in 
bank-switched memory, and therefore must be carefully selected 
and deselected. Second, a request for an unsupported device 
function may produce undesirable results. 

There are four inputs stored in six zero page locations that 
must contain the appropriate information when a call is made to 
a device driver. The first input is the Command Code, which 
indicates which operation is requested. As mentioned earlier, four 
operations are currently defined. The first of these is STATUS, 
which is used to determine if the device is ready to be accessed 
(either Read or Write). Although not all device drivers do so, it is 
suggested that the number of blocks the device supports be 
returned, in additon to the status. This should be done using the X 
(low byte) and Y (high byte) registers. The remaining operations 
are quite straightforward—READ for reading a block, WRITE 
for writing a block, and FORMAT to format or initialize the 
media. 

The second input is the Unit Number, indicating in which slot 
and drive the desired device resides. Only two drives per slot are 
supported directly, but it is possible to interface a controller card 
that supports additional drives or volumes. 

The third input is a 2-byte Buffer Pointer that indicates the 
location of a 512-byte area for data transfer. The MLI verifies 
that no memory conflicts exist, but most device drivers will not do 
so; therefore, some degree of care should be exercised in 
determining this input. 

The fourth input is a 2-byte Block Number indicating which 
block is to be used for data transfer. The value should be in 
keeping with the number of blocks available on the desired 
device. 

The four inputs necessary are listed in Table 6.4. 

Although Apple has defined the manner in which device 
drivers are to be called, some variations will occur. Even the 
drivers provided by Apple vary slightly from one another. For 
this reason it is advisable to make calls to any device driver with 
great caution. The parameter list descriptions that follow detail 
the four kinds of calls that are available. Not all device drivers 
will support all four call types and a request to an unsupported 
call type could prove dangerous. 
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Table 64 Device Driver Parameters— General Format 


LOCATION | DESCRIPTION | OPTIONS 











$42 | Command code |$00 =STATUS 
$01 = READ 
$02 = WRITE 
$03 = FORMAT 







DSSS0000 
D = Drive number (0 = drive 1, 
1=drive 2); SSS=Slot number 


$43 | Unit Number 
(0 to 7) 


$44-45 | I/O Buffer Can be $0000 to $F FFF 
Block Number | Can be $0000 to $F FFF 


fo The processor CARRY flag is 


set upon return from the device 
driver if an error occurred. 
The ACCUMULATOR 
contains the return code. 
$00 = Noerrors 
$27 = 1/Oerror 
$28 = No device connected 
$2B = Write protect error 
CALLING THE DISK 11 DEVICE DRIVER 

Access to standard Apple floppy disk drives (Disk II or equiva- 
lent) is performed using the Disk II Device Driver provided with 
ProDOS. As mentioned above, the Disk II Device Driver does not 
support the FORMAT call. If such a request is made, it will be 
interpreted as a WRITE call, and serious problems may result. 
Formatting floppy disks is performed by the separate utility 
program called FILER. 

The I/O buffer location is not checked for validity by the Disk 
II Device Driver. The block number must be in the range $0-$117 
or an error type $27 (I/O error) will result. 

The Disk IT Device Driver performs the same READ and 
WRITE functions as the RWTS routines of DOS 3.3, but these 
routines have been substantially modified to decrease disk access 
time. A comparison of RWTS to the Disk II Device Driver is 
contained in Understanding the Apple IIe by Jim Sather (1985, 
Quality Software). 
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DEVICE DRIVER PARAMETER LISTS BY COMMAND CODE 


key 






FUNCTION This call returns the status of a particular device 
and is generally used to determine if a device is 
present, and if so, whether it is write protected. 
Additionally, some drivers will return the 
number of blocks supported by that device. 


REQUIRED INPUTS 
$42 Must be $00. 
$43 Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0 = drive 1, 1=drive 2) and SSS is the slot 
number (1—7). 
$44-45 Unused. 
$46-47 Unused but sometimes checked for validity (use 


$0000). 
RETURNED VALUES 
Carry Flag Clear —Noerror occurred 
Set —Error occurred (see Accumulator for 
type) 
-Accumulator $00 —Noerrors 
$27 —I/Oerror or bad block number 
$28 —Nodevice connected to unit 


$2B —Disk is write protected 


X-register Blocks available (low byte) 
Y-register Blocks available (high byte) 





$01 READiequest | 





FUNCTION This call will read a 512-byte block and store it 
at the specified memory location. Most drivers 
will not check the memory location, so some care 
is suggested. 
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REQUIRED INPUTS 


$42 


$43 


$44-45 


$46-47 


RETURNED VALUES 


Carry Flag 


Accumulator 


Must be $01 

Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0=drive 1, 1 =drive 2), and SSS is the slot 
number (1—7). 

Address (LO/HI) of the caller’s 512-byte buffer 
into which the block will be read. The buffer 
need not be page aligned. 

Block number (LO/HI) to read. Must be valid for 
the device being called. 


Clear —Noerror ocurred. 
Set —Error occurred (see Accumulator for 
type) 


$00 —Noerrors 
$27  —I/Oerror or bad block number 
$28 —Nodevice connected to unit 





FUNCTION 


REQUIRED INPUTS 


$42 
$43 


$44-45 


$46-47 


This call will write a 512-byte block from the 
specified memory location. Since all write 
operations could potentially destroy data, care is 
suggested. 


Must be $02 

Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0=drive 1, 1 = drive 2), and SSS is the slot 
number (1—7). 

Address (LO/HI) of the caller’s 512-byte buffer 
into which the block will be read. The buffer 
need not be page aligned. 

Block number (LO/HI) to read. Must be valid for 
the device being called. 
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RETURNED VALUES 
Carry Flag Clear —Noerror ocurred 
Set —Error occurred (see Accumulator for 
type) 
Aecumulator $00 —Noerrors 


$27 —I/Oerror or bad block number 
$28: —Nodevice connected to unit 
$2B —Disk is write protected. 





FUNCTION This call will format the media present in the 
specified device. Since all data will be destroyed, 
extreme care is suggested. 


REQUIRED INPUTS 
$42 Must be $03 
$43 Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0= drive 1, 1=drive 2), and SSS is the slot 
number (1—7). 


RETURNED VALUES 
Carry Flag Clear —Noerror ocurred 
Set —Error occurred (see Accumulator for 
type) 
Accumulator $00 —Noerrors 


$27 —I/Oerror or bad block number 
$28 —Nodevice connected to unit 
$2B —Disk is write protected 


Returncode $00 —Noerrors 
$27 —I/Oerror 
$28 —Nodevice connected 


$2B —Write protected 
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CALLING THE MACHINE LANGUAGE INTERFACE 


The Machine Language Interface (MLI) consists of a set of 
externally callable subroutines in the ProDOS Kernel. Over 20 
different functions may be performed to access and manipulate 
files in a device independent manner (i.e. the programmer need 
not be concerned with whether the device is a diskette drive or a 
hard disk). To avoid duplication of code and to eliminate direct 
calls to unpublished entry points within ProDOS, it is 
recommended that all file access be performed using the 
standardized ProDOS Machine Language Interface. 

All calls to the MLI are made through the System Global Page at 
$BF00. The first item in this page is a JMP (GOTO) to the MLI. 
Thus, to call the MLI, code the following: 


JSR SBEG@ 
DFB function code 
DW addr of parms 


where “function_code” should be replaced with a 1-byte 
hexadecimal code representing the function you want to perform, 
and “addr_of_parms” is the 2-byte address of a parameter list 

you have created in your program’s memory which indicates such 
thing's as the file name being accessed, the record number to 
access, etc. Note that programming reentrant or “ROMable” code 
or routines that cannot have instructions mixed with data will be 
made more difficult by this convention. In these cases, it may be 
advisable to move the JSR $BF00, the three bytes following, anda 
RTS instruction toa RAM data area and call them there. 

Upon return, the processor CARRY flag will be set if an error 
has occurred, and the return code will be placed in the A register. 
All other registers are saved and restored by the MLI. The valid 
function_codes are summarized in Table 6.5. It is interesting to 
note that most of the function calls are identical between ProDOS 
and the Apple III SOS operating system. The names used are the 
standardized labels for these functions established by Apple for 
SOS and ProDOS. 
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Table 6.5 MLt Functions 


CODE| NAME DESCRIPTION 


ALLOC_INTERRUPT Install interrupt handler 
DEALLOC_INTERRUPT] Remove interrupt handler 


QUIT 


READ_BLOCK 
WRITE_BLOCK 
GET_TIME 


CREATE 
DESTROY 
RENAME 
SET_FILE_INFO 
GET_FILE_INFO 
ONLINE 


SET_PREFIX 


GET_PREFIX 


GET_BUF 


Exit from one Interpreter and 
dispatch another 

Read disk block by unit number 
Write disk block by unit number 
Read calendar/clock peripheral 
card and set system date/time 
Create a new file or directory 
Delete a file or directory 
Rename a file or directory 
Change a file’s attributes 
Return a file’s attributes 
Return names of one or all 
online volumes 

Change default pathname 
prefix 

Return default pathname prefix 
Open a file 

Set end-of-line character for 
line-by-line reads 

Read one or more bytes from an 
open file 

Write one or more bytes to an 
open file 

Close one or more open files, 
flushing buffers 

Flush all write buffers for one 
or more files 

Change File Position within an 
open file 

Return File Position within an 
open file 

Change end-of-file position of 
an open file 

Return end-of-file position of an 
open file 

Change File Buffer’s address 
for an open file 

Return File Buffer’s address 
for an open file 
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The general form for a parameter list is as follows: 






PARAMETER 


+0 
COUNT 






+7 one or more parameters 






The PARAMETER_COUNT isa 1I-byte count of the number of 
parameters which follow. It is used by the MLI to validity check 
the parameter list to make sure that the address following the 
caller’s JSR to the MLI really points to a valid parameter list. 


ine 


iit 
A 

$ 

ASSEMBLY 
LAN GUAGE 

PROGRAMMERS | | 


= | ; LG Je I lh] Se} 
Ry > = “eB: 
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c- 





| 


wie l 
oF ~é spf 
4 
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BE PREPARED! YOURE ENTERING THE DEPTHS OF Pro DOS. 
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MLI PARAMETER LISTS BY FUNCTION CODE 





$40 ALLOCINTERRUPT: 
_ INSTALLINTERRUPTHANDLER 





FUNCTION This function allows the user to install his own 
interrupt handling routine into the ProDOS 
table. The user’s handler resides in memory 
outside ProDOS, and only its entry point address 
is stored in the System Global Page table by this 
MLI call. Up to four such routines may be 
installed at any time. When a maskable 
interrupt (IRQ) occurs, ProDOS calls each 
handler in the order in which they were installed 
to allow the interrupt to be serviced. (See 
Chapter 7 for more information about writing 
interrupt handlers.) 


PARAMETER LIST FORMAT 







+0 
+1 PRIORITY 
209 ny 
REQUIRED INPUTS 


+0 Parameter count (2 parameters in list). 
+2/+3 Address (LO/HI format) of user-written 
interrupt handling routine. 


RETURNED VALUES 


+1 Priority assigned to this handler by ProDOS: 1, 
2,3 or 4. This is the handler’s position in the 
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calling sequence. It is assigned the highest 
priority (earliest position) available. 
Return Code $00 —Noerrors 
$04 — Parameter count is not $02 
$25 —Interrupt handler table full (4 are 
installed) 
$53 —Invalid parameter in list (address is zero) 





"$41. DEALLOC-INTERRUPT: _ 
"REMOVE INTERRUPT HANDLER 


FUNCTION This function removes a previously installed 
interrupt handling routine’s address from the 
ProDOS table. 


PARAMETER LIST FORMAT 


+0 


+1 PRIORITY 


REQUIRED INPUTS 
+0 Parameter count (1 parameter in list). 
+1 Priority of handler to be removed (1, 2, 3, or 4) as 
returned by MLI call $40 when it was installed. 


RETURNED VALUES 
Return Code $00 —Noerrors 
$04 —Parameter count is not $01 
$53 —Invalid parameter in list (PRIORITY is 
not 1, 2, 3, or 4) 


ae ate ae ee 5 our: : : 
EXIT FROM ON E INTERPRETER, DISPATCH. ANOTHER 


FUNCTION This function causes the MLI to move three 
pages of code from $D100 in the alternate 4K of 
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the Language. card to $1000 and branch to it. 
This code frees any memory allocated by the 
interpreter in the System Memory Bit Map in 
the System Global Page, and then prompts the 
user for the name of a new Interpreter (System 
Program) to be executed. It then loads the new 
Interpreter and executes it. For more 
information on this call and on writing an 
Interpreter, see Chapter 7. 


PARAMETER LIST FORMAT 


po 














+0 
+5/+6 





REQUIRED tNPUTS 


+0 Parameter-count (4 parameters in list). 
+1—+6 All other fields in the parameter list are 
reserved for future use. They must be present 
and they must be initialized to.zeroes. 


RETURNED VALUES 
Return Code $04 — Parameter count is not $04 
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$80 READ_BLOCK: 
D DISK BLOCK BY UNIT NUMBER 


FUNCTION This function calls the device handler for a given 
unit to read a 512-byte disk block. Calling this 
function is essentially the same as calling the 
device driver directly with the following 
additional actions: the buffer memory is validity 
checked for prior use; interrupts are disabled 
prior to the call to the driver; the unit number is 
validity checked and mapped into the appro- 
priate device driver’s address; the bank switched 
memory (language card) is enabled prior to the 
call and restored to its previous condition when 
the call completes. For these reasons, it is 
recommended that al] block I/O be performed 
through the READ_BLOCK and 
WRITE_BLOCK MLI calls rather than calling 
the drivers directly. Direct calls are only 
recommended when the application will not be 
using the ProDOS Kernel and only the driver 
itself is available in memory. 


PARAMETER LIST FORMAT 






+0 
“ UNIT NUMBER 
12/93 ADDRESS OF 
DATA BUFFER 
+4/+5 BLOCK NUMBER 
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REQUIRED INPUTS 
+0 Parameter count (3 parameters in list). 
+1 Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0= drive 1, 1 = drive 2) and SSS is the slot 
number (1 through 7). 
+2/+3 Address (LO/HI) of the caller’s 512-byte buffer 
into which the block will be read. The buffer 
need not be page aligned. 
+4/+5 Block number (LO/HI) to read. This may range 
from $0000 to $0117 for a diskette. The validity 
of this number is checked by the driver itself. 


RETURNED VALUES 
Return Code $00 —Noerrors 
$04 — Parameter count is not $03 
$27 —1/Oerror or bad block number 
$28 — No device connected to unit 
$56 —Bad buffer (already.in use by ProDOS) 






a $81 WRITE_BLOCK: 
(TE DISK BLOCK BY UNIT N UMBER 





FUNCTION This function calls the device handler for a given 
unit to write a 512-byte disk block. Calling this 
function is essentially the same as calling the 
device driver directly with the following 
additional actions: the buffer memory is validity 
checked for prior use; interrupts are disabled 
prior to the call to the driver; the unit number is 
validity checked and mapped into the appro- 
priate device driver’s address; the bank switched 
memory (language card) is enabled prior to the 
call and restored to its previous condition when 
the call completes. For these reasons, it is 
recommended that all block I/O be performed 
through the READ_BLOCK and 
WRITE_BLOCK MLI calls rather than calling 
the drivers directly. Direct calls are only 
recommended when the application will not be 
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using the ProDOS Kernel and only the driver 
itself is available in memory. 


PARAMETER LIST FORMAT 









+0 
1 UNIT NUMBER 
+2/+3 ADDRESS OF 
DATA BUFFER 
+4/+5 BLOCK NUMBER ” 
REQUIRED INPUTS -: 


+0 Parameter count (3 parameters in list). 
+1 Unit number of disk to be accessed. The bit 
assignment of a ProDOS unit number is as 
follows: DSSS0000, where D is the drive number 
(0= drive 1, 1=drive 2) and SSS is the slot 
number (1 through 7). 
+2/+38 Address (LO/HI) of the ealler’s 512-byte buffer 
from which the block will be written. The buffer 
need not be page aligned. 
+4/+5 Block number (LO/HI) to write. This may range 
from $0000 to $0117 for a diskette. The validity 
of this number is checked by the driver itself. 


RETURNED VALUES. 
Return Code $00 —Noerrors 
$04 — Parameter count is not $03 
$27 —1/Oerror or bad block number 
$28 —No device connected.to unit 
$2B — Disk is write protected 
$56 —Bad buffer (already in use by ProDOS) 
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FUNCTION 


PARAMETER LIST 
None 


REQUIRED INPUTS 
None 


RETURNED VALUES 


$BF90/$BF91 


$BF92/$BF93 


Return Code 





FUNCTION 


REs D CALENDAR/CLOCK PERIPHERAL CARD. 


CREATE ANEW FILE OR DIRECTORY | 


-$82.. GET_TIME: 





This function accesses any calendar/clock card 
which might be in the system and sets the 
system date and time in the System Global 
Page. If no calendar/clock handler has been 
installed (DATETIME vector in the System 
Global Page), the call is ignored. 


(parameter list address following JSR is $0000) 


System Global Page date field is filled in. Its 
format is (LO/HI): YYYYYYYM 
MMMDDDDD where YYYYYYY is the year 
(offset from 1900), MMMM is the month (1 
through 12), and DDDDD is the day. 

System Global Page time field is filled in. Its 
format is (LO/HI): HHHHHHHH 
MMMMMMMM where HHHHHHHuH is the 
hour since midnight and MMMMMMMM is 
the minute (0 through 59). 

$00 —Noerrors 


$CO CREATE: 





This function creates a new file (either a data file 
or a directory file). One 512-byte block of disk 
space is allocated to the new file. The file may 
not already exist. If it is desirable to recreate an 
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old file, issue the DESTROY call first. If the 
pathname given indicates that the file’s 
directory entry will be in a subdirectory and 
there are no free directory entries there, the 
subdirectory will be extended by one block. The 
Volume Directory may not be extended. If the 
new file is a directory file, a directory header is 
created and written to the key block. 


PARAMETER LIST FORMAT 
+0 


ADDRESS OF 
+i/+2 PATHNAME 


ACCESS 
+3 BITS 
FILE 
*@ TYPE 


AUXILIARY 
+5/+6 FILE TYPE 


7 STORAGE 
TYPE 
CREATION 
+8/+9 DATE 
CREATION 
+AI+B TIME 





REQUIRED INPUTS 


+0 
+1/+2 


+3 


+4 
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Parameter count (7 parameters in list). 

Address (LO/HI) of pathname buffer for file to 
be created. The pathname buffer consists of a 1- 
byte length followed by 1 to 63 characters of 
name. If the first character is a “/”, the name is 
considered to be fully qualified. If not, the 
current default prefix is added to the name by 
ProDOS when the file is created. 

Access privileges associated with this file. The 
access bits are: 

DNBXXXWR 

(high bit to low bit) where... 

Ds (bit 7) if 1 allows the file to be DESTRO Yed. 
N (bit 6) if 1 allows the file to be RENAMEd. 
B_ (bit 5) if 1 indicates file needs backing up. 
X = (bits 4, 3, and 2) are reserved for future use. 
W s(bit 1) if 1 allows the file to be written. 

R (bit 0) if 1 allows the file to be read. 


Full access is $C3. A file is “locked” in the 
BASIC interpreter sense if the D, N, W and R 
bits are all zeroes. It is unlocked if they are all 
ones. The B bit is forced to one when the file is 
created. WARNING: It is possible to set the “X” 
reserved bits to ones with this call since no 
validity check is made by the MLI on CREATE 
(a check is made for SET_FILE_INFO, 
however). 

Type of data stored in the file. Commonly 
supported file types are: 


File containing bad blocks. 
File containing ASCII text 
(BASIC data file). 


File containing a binary 


memory image or machine 
language program. 

File is a directory. 
AppleWorks data base file 
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AppleWorks word processing 
file 

AppleWorks spread sheet file 
ProDOS added command file. 
User defined file types. 

File contains an Applesoft 


program. 


File contains Applesoft 
variables (STORE/ 
RESTORE). 

File contains a relocatable 
object module (EDASM). 
File contains a ProDOS 
system program. 





Other less commonly used file types are defined 
in APPENDIX E. Assignment of a file type isa 
convention which serves to inform the program 
which accesses a file what data format it should 
expect to find there. You are not prevented from 
storing binary data ina TXT file or ASCII text 
ina BIN file, but this runs counter to convention 
and is discouraged. 

+5/+6 Auxiliary data pertaining to the file. Its usage is 
defined according to its file type above. The 
current uses of this field by the BI are: 


contains the default record length 
(LO/HD). 

contains the address (LO/HI) at which to 
load the image. 

contains the address (LO/HI) of the 


BASIC program image. 

contains the address (LO/HI) of the 
BASIC variables image. 

contains $2000 (LO/HI), the load address 
for system files. 
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+7 Storage type or type of file organization. If this 
byte contains $0D, the file is a linked 
subdirectory file. If it is $01, it is a standard 
seedling file (at the time of its creation). Other 
values are reserved for future use. If a value of 
$00, $02, or $03 is given, $01 is assumed. All 
values other than $00-$03 or $0D will result in 
anerror. 


+8/+9 Date of creation. If this field is set to zero, the 
MLI uses the current system date (if any). If this 
field is non-zero, it is the creation date in the 
(LO/HI) form YYYYYYYM MMMDDDDD 
where YYYYYYY is the year past 1900, 
MMMM is the month (1-12) and DDDDD is the 
day of the month. 


+A/+B Time of creation. If this field is set to zero, the 
MLI uses the current system time (if any). If this 
field is non-zero, it is the creation time in the 
(LO/HI) form HHHHHHHH MMMMMMMM 
where HHHHHHHH is the hour past midnight 
and MMMMMMMM is the minute within the 
hour. 


RETURNED VALUES 


Return Code $00 —Noerrors 
$04 — Parameter count is not $07 
$27 —I/Oerror 
$2B — Disk is write protected 
$40 — Pathname has invalid syntax 
$44 — Path to file’s subdirectory is bad 
$45 — Volume directory not found 
$47 — Duplicate file name already in use 
$48 — Disk full 
$49 — Volume directory full 
$4B — Bad storage type (use only $0D or $01) 
$53 —Invalid parameter or address pointer 
$5A — Damaged disk freespace bit map 
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SLETE AF FILE. OR DIRECTO 


FUNCTION This function deletes a file or empty 
subdirectory. Open files may not be deleted. The 
Volume Directory may not be deleted. A 
subdirectory is considered “locked” if it contains 
any files at all, and may not be DESTROYed 
until all its files and subdirectories are 
DESTROYed. 


PARAMETER LIST FORMAT 


+0 


ADORESS OF 
PATHNAME 


+1/+2 





REQUIRED INPUTS 
+0 Parameter count (1 parameter in list). 

+1/+2 Address (LO/HI) of pathname buffer for file to 
be deleted. The pathname buffer consists of a 1- 
byte length followed by 1 to 63 characters of 
name. If the first character is a “/”, the name is 
considered to be fully qualified. If not, the 
current default prefix is added to the name by 
ProDOS. 


RETURNED VALUES 

Return Code $00 —Noerrors 
$04 — Parameter count is not $01 
$27 —I/Oerror 
$2B — Disk is write protected 
$40 — Pathname has invalid syntax 
$44 — Path to file’s subdirectory is bad 
$45 — Volume directory not found 
$46 —File not found in specified directory 
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$4A —Incompatible file format 

$4B — Bad storage type 

$4E — Access refused: DESTROY bit not 
enabled or non-empty subdirectory 

$50 — Access refused: File is currently open 

$5A — Damaged disk freespace bit map 











- 2302 RENAME: 
RENAME A FILEOR DIRECTORY. 





FUNCTION This function renames a file or subdirectory. 
Only the final name in the path specification 
may be renamed. This function will not rename 
multiple directories in a pathname specification 
(e.g. /project/myfile may not be renamed to 
/task/yourfile since this involves renaming 
something other than the final name in the 
pathname). RENAME will not create new 
subdirectories or move a file’s entry from one 
directory to another (e.g. you may not rename 
/project/myfile to /project/another/myfile since 
this involves moving the file’s entry to 
subdirectory “another”). A volume may be 
renamed if no files are currently opened for it. A 
file or subdirectory may be renamed if it is not 
open, or if it is a read-only file (WRITE access 
disabled). The new file name may not be the 
same as another in the same directory. 


PARAMETER LIST FORMAT 
+0 
+1/+2 ADDRESS OF 
OLD PATHNAME 
43/44 ADDRESS OF 


NEW PATHNAME 
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REQUIRED INPUTS 


+0 
+1/+2 


+3/+4 


Parameter count (2 parameters in list). 

Address (LO/HI) of pathname buffer for file to 
be renamed. The pathname buffer consists of a 
1-byte length followed by 1 to 63 characters of 
name. If the first character is a “/”, the name is 
considered to be fully qualified. If not, the 
current default prefix is added to the name by 
ProDOS. 

Address (LO/HI) of pathname buffer for the new 
name. The qualifying levels of the name, if any, 
should match those of the old pathname given at 
+1/+2. Only the last name should be different. 
The format of the new pathname buffer is 
identical to that of the old pathname buffer 
given above. The current default prefix, if any, 
will be added toa non-fully qualified pathname. 


RETURNED VALUES 
Return Code 





$00 —Noerrors 

$04 — Parameter count is not $02 

$27 —I/Oerror 

$2B — Disk is write protected 

$40 — Pathname has invalid syntax 

$44 — Path to file’s subdirectory is bad 

$45 — Volume directory not found 

$46 —File not found in specified directory 

$47 — New name duplicates one already in 
directory 

$4A —Incompatible file format 

$4B — Bad storage type 

$4E — Access refused: RENAME bit not enabled 

$50 — Access refused: File is currently open 

$57 — Two volumes are online with the same 
volume name 


$03 SET-FILEINFO: 
HANGE PILES STU RURUT ES ae 





FUNCTION This function changes.the attributes (e.g. file 


type, storage type, etc.) which are stored in the 
directory entry which describes a file. The file 
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may be open or closed. SET_FILE_INFO will 
not act upon a Volume Directory (an error of $40 
will result). Before issuing this function call, it is 
recommended that GET_FILE_INFO ($C4) be 
used to determine the current parameter 
settings for the file. (Note that the parameter 
lists for the two calls have a compatible format.) 


PARAMETER LIST FORMAT 


+0 


+4/+2 ADDRESS OF 
PATHNAME 


4 ACCESS 
BITS 
; FILE 
: TYPE 


+5/+6 AUXILIARY 


FILE TYPE 


+7 
+8/+9 
“AB MODIFICATION 
eng TIME OF LAST 


MODIFICATION 
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REQUIRED INPUTS 
+0 
+1/+2 


+3 


+4 





Parameter count (7 parameters in list). 

Address (LO/HI) of pathname buffer for file. 
The pathname buffer consists of a 1-byte length 
followed by 1 to 68 characters of name. If the 
first character is a “/”, the name is considered to 
be fully qualified. If not, the current default 
prefix is added to the name by ProDOS. 

New access privileges to be associated with this 
file. The access bits are: 

DNBXXXWR 

(high bit to low bit) where... 

(bit 7) if 1 allows the file to be DESTROYed. 
(bit 6) if 1 allows the file to be RENAMEd. 
(bit 5) if 1 indicates file needs backing up. 
(bits 4, 3, and 2) are reserved for future use. 
(bit 1) if 1 allows the file to be written. 

(bit 0) if 1 allows the file to be read. 

Full access is $C3. A file is “locked” in the 
BASIC interpreter sense if the D, N, Wand R 
bits are all zeroes. It is unlocked if they are all 
ones. Note that a “locked” file is not protected 
against SET_FILE_INFO (how else would one 
unlock it?). If an attempt is made to use the “X” 
reserved bits, an error will occur. They should be 
set to zeroes. 

Type of data stored in the file. Commonly 
supported file types are: 


Dax wzy 


File containing bad blocks. 
File containing ASCII text 
(BASIC data file). 

File containing a binary 
memory image or machine 
language program. 


File is a directory. 
AppleWorks data base file 
AppleWorks word processing 
file 

AppleWorks spread sheet file 
ProDOS added command file. 


+5/+6 


+7 
+8/+9 
+A/+B 
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$F1-$F8 User defined file types. 

$FC File contains an Applesoft 
program. 

$FD File contains Applesoft 
variables (STORE/ 


RESTORE). 
$FE File contains a relocatable 
object module (E DASM). 
$FF File contains a ProDOS 
system program. 





Other less commonly used file types are defined 
in APPENDIX E. Assignment of a file type isa 
convention which serves to inform the program 
which accesses a file what data format it should 
expect to find there. You are not prevented from 
storing binary data ina TXT file or ASCII text 
ina BIN file, but this runs counter to convention 
and is discouraged. 

Auxiliary data pertaining to the file. Its usage is 
defined according to its file type above. The 
current uses of this field by the BI are: 





contains the default record length 
(LO/HI). 

contains the address (LO/HI) at which to 
load the image. 

contains the address (LO/HI) of the 
BASIC program image. 

contains the address (LO/HI) of the 
BASIC variables image. 

contains $2000 (LO/HI), the load address 
for system files. 












Ignored. May be set to zero. 

Ignored. May be set to zero. 

Date of last modification. If this field is set to 
zero, the MLI uses the current system date (if 
any). If this field is non-zero, it is the 
modification date in the (LO/HI) form 
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+C/+D 


RETURNED VALUES 


Return Code 





FUNCTION 


YYYYYYYM MMMDDDDD where 
YYYYYYY is the year past 1900, MMMM is the 
month (1-12) and DDDDD is the day of the 
month. 

Time of last modification. If this field is set to 
zero, the MLI uses the current system time (if 
any). If this field is non-zero, it is the 
modification time in the (LO/HI) form 
HHHHHHHH MMMMMMMM where 
HHHHHHHH is the hour past midnight and 
MMMMMMMM is the minute within the hour. 


$00 —Noerrors 

$04 — Parameter count is not $07 

$27 —I/Oerror 

$2B — Disk is write protected 

$40 —Pathname has invalid syntax 

$44 — Path to file’s subdirectory is bad 

$45 — Volume directory not found 

$46 — File not found in specified directory 

$4A — Incompatible file format 

$4B — Bad storage type 

$4E — Access refused: Reserved access bits 
were used 

$53 — Parameter value out of range 

$5A — Damaged disk freespace bit map 


$C4. GET_FILE_INFO: 


: atte FILE'S ATTRIBUTES 


This function reads the attributes (e.g. file type, 
storage type, etc.), which describe the file and 
are stored in the directory entry, and returns 
them in the parameter list provided by the 
caller. The file may be open or closed. If 
information about a Volume Directory is 
requested, the size of the volume in bloeks and 
the blocks in use count are also returned. 
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PARAMETER LIST FORMAT 
+0 
ADDRESS OF 
+1/42 PATHNAME 


3 ACCESS 
BITS 
FILE 
. 


AUXILIARY 
+5/+6 FILE TYPE 
. STORAGE 
TYPE 

+8/+9 
tice DATE OF LAST 

MODIFICATION 
“CHD TIME OF LAST 


MODIFICATION 


CREATION 
nee DATE 
+10/+11 See 





6-33 


6-34 Beneath Apple ProDOS 


REQUIRED INPUTS 
+0 Parameter count ($A parameters in list). 

+1/+2 Address (LO/HI) of pathname buffer for file. 
The pathname buffer consists of a 1-byte length 
followed by 1 to 63 characters of name. If the 
first character is a “/”, the name is considered to 
be fully qualified. If not, the current default 
prefix is added to the name by ProDOS. 


RETURNED VALUES 
+3 Access privileges associated with this file. The 
access bits are: 
DNBXXXWR 
(high bit to low bit) where... 
(bit 7) if 1 allows the file to be DESTORYed. 
(bit 6) if 1 allows the file to be RENAMEd. 
(bit 5) if 1 indicates file needs backing up. 
(bits 4, 3, and 2) are reserved for future use. 
(bit 1) if 1 allows the file to be written. 
(bit 0) if 1 allows the file to be read. 
Full access is $C3. A file is “locked” in the 
BASIC interpreter sense if the D, N, Wand R 
bits are all zeroes. It is unlocked if they are all 
ones. 
+4 Type of data stored in the file. Commonly 
supported file types are: 


Dar w zy 


File containing bad blocks. 
File containing ASCII text 
(BASIC data file). 

File containing a binary 
memory image or machine 
language program. 


File is a directory. 
AppleWorks data base file 
AppleWorks word processing 
file 

AppleWorks spread sheet file 
ProDOS added command file. 
User defined file types. 
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File contains an Applesoft 


program. 
File contains A pplesoft 
variables (STORE/ 
RESTORE). 


File contains a relocatable 
object module (EDASM). 
File contains a ProDOS 
system program. 





Other less commonly used file types are defined 
in APPENDIX E. Assignment of a file type isa 
convention which serves to inform the program 
which accesses a file what data format it should 
expect to find there. You are not prevented from 
storing binary data ina TXT file or ASCII text 
ina BIN file, but this runs counter to convention 
and is discouraged. 


+5/+6 Auxiliary data pertaining to the file. Its usage is 
defined according to its file type above. The 
current uses of this field by the BI are: 


contains the default record length 
(LO/HD. 

contains the address (LO/HI) at which to 
load the image. 

contains the address (LO/HI) of the 


BASIC program image. 

contains the address (LO/HI) of the 
BASIC variables image. 

contains $2000 (LO/HD), the load address 
for system files. 





If the GET_FILE_INFO request is for the 
Volume Directory, this field contains the size of 
this volume in blocks. 


+7 Storage type or type of file organization. 
Currently supported storage types are: 
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+8/+9 


+A/+B 


+C/+D 


+E /+F 


+10/+11. 


Return Code 









$0Dj] Linked directory file 
$01 |Seedling file (no index blocks) 
$02 |Sapling file (one index level) 

Tree file (two index levels) 








Other values are reserved for future use. 
Number of 512-byte disk blocks in use by file 
including index blocks and data blocks. If the 
GET_FILE_INFO cal] is made on the volume 
itself (Volume Directory), this field contains the 
total number of disk blocks in use on the volume 
(including system overhead).. 

Date of last modification. If this field is non-zero, 
it is the date of the last modification in the 
(LO/HI) form YYYYYYYM MMMDDDDD 
where YYYYYYY is the year past 1900, 
MMMM is the month (1-12) and DDDDD is the 
day of the month. 

Time of last modification. If this field is non- 
zero, it is the time of the last modification in the - 
(LO/HD form HHHHHHHH MMMMMMMM 
where HHHHHHHH is the hour past midnight 
and MMMMMMMM is the minute within the 
hour. 

Date of file’s creation. If this field is non-zero, it 
is the creation date in the (LO/HI) form 
YYYYYYYMMMMDDDDD where 
YYYYYYY is the year past 1900, MMMM is the 
month (1-12) and DDDDD is the day of the 
month. 

Time of file’s creation. If this field is non-zero, it 
is the creation time in the (LO/HI) form 
HHHHHHHH MMMMMMMM where 
HHHHHHHH is the hour past midnight and 
MMMMMMM Mis the minute within the hour. 
$00 —Noerrors 

$04 — Parameter count is not $0A 

$27 —I/O error 

$40 — Pathname has invalid syntax 

$44 — Path to file’s subdirectory is bad 

$45 — Volume directory not found 

$46 — File not found in specified directory 
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FUNCTION 


N NAMES OF ONE OR ALL ‘ONLINE VOLUME 


$4A — Incompatible file format 

$4B — Bad storage type 

$53 — Parameter value out of range 
$5A — Damaged disk freespace bit map 





-$CB ‘ONLIN E: 


This function examines all mounted disk 
volumes and returns their names in the buffer 
provided by the caller. If a single volume is to be 
identified, the caller must provide a specific unit 
number (slot and drive). 


PARAMETER LIST FORMAT 


+0 


+4 


+2/+3 


REQUIRED INPUTS 
+0 
+1 


+2/+3 






UNIT NUMBER 





ADDRESS OF 
DATA BUFFER 






Parameter count (2 parameters in list). 

Unit number of specific device to be examined. 
If all online volumes are to be identified, set this 
field to zero. The bit assignment for a specific 
unit number is: DSSS0000, where D is the drive 
number (0=drive 1, 1=drive 2) and SSS is the slot 
number (1 through 7). 

Address (LO/HI) of a buffer to contain the 
volume names returned by ProDOS. If a specific 
unit is to be examined, a 16-byte buffer must be 
provided. If the call is non-specific (UNIT = 0), 
then the buffer must be 256 bytes to allow for up 
to 16 online volumes. 
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RETURNED VALUES 


Buffer 


Return Code 


If the return code in the accumulator is zero, the 
caller’s buffer will contain zero or more volume 
name entries of format described below. The 
volume names will be given in the order in which 
ProDOS searches for a volume, i.e. the boot 
volume first, followed by slot numbers lower 
than the boot slot, wrapping around to higher 
slots last. 


ONLINE VOLUME ENTRY 









DSSSLLLL: where D is the drive 
number (0=drive 1, 1=drive 2), SSS is 
the slot number (1 through 7), and 
LLLL is the length of the name 
which follows. If LLUL is zero, an 
error occurred in examining this 
volume. The return code is in the 
first byte of the name field. If byte 0 
is zero, then there are no more 
volume entries in the buffer. 


bytes 1-15] Volume name or 1-byte error code. 
No slash precedes the name. 
$00 —Noerrors 
$04 — Parameter count is not $02 
$55 — Volume Control Block full (too many open 
files) 


$56 — Bad buffer address (check system 
memory bit map) 










The following error codes may appear for a 
specific unit in byte 1 of a buffer entry. If so, the 
return code above will be $00. 


$27 —I/Oerror on this unit 

$28 — Device not connected (e.g. no drive 2) 

$2E — Diskette switched while file was open 

$45 — Volume directory not found 

$52 — Nota ProDOS disk volume 

$57 — Duplicate volume—Byte 3 of buffer entry 
contains the unit number of the duplicate 
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ee $C6 SET_PREFIX: 
_ CHANGE DEFAULT PATHNAME PREFIX — 





FUNCTION This function changes the default prefix which is 
attached to any pathnames passed to the MLI 
which are not fully qualified (do not start witha 
slash). The MLI follows the prefix given, 
locating each directory at each level of the prefix 
to make sure that they exist on a mounted 
volume. 


PARAMETER LIST FORMAT 


ano ADDRESS OF 
PATHNAME 
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REQUIRED INPUTS 
+0 Parameter count (1 parameter in list). 

+1/+2 Address (LO/HI) of pathname buffer for the new 
prefix. The pathname buffer consists of one byte 
of length followed by 1 to 63 characters of name. 
If the first character is a “/”, the name is 
considered to be fully qualified. If not, the old 
default prefix is added to the new one to forma 
completely qualified default prefix (for a total 
length of no more than 64 characters). The last 
name in the prefix must be that of a directory 
file. The prefix may be eliminated by specifying 
a null (0 length) prefix. An ending slash is 
assumed if it is omitted. 


RETURNED VALUES 
Return Code $00 —Noerrors 
$04 — Parameter count is not $01 
$40 — Pathname has invalid syntax or prefix 
too long 
$44 — Path to final subdirectory is bad 
$45 — Volume directory not found 
$46 — Final subdirectory file not found 
$4A —Incompatible file format 
$4B — Bad storage type 
$5A — Damaged disk freespace bit map 





FUNCTION This function returns the default prefix, if any, 
to the caller’s buffer. 


PARAMETER LIST FORMAT 


+0 


pe ADDRESS OF 
PATHNAME 
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REQUIRED INPUTS 


+0 Parameter count (1 parameter in list). 
+1/+2 Address (LO/HI) of pathname buffer into which 
the MLI will copy the default prefix. The buffer 
must be at least 64 bytes long. 
RETURNED VALUES 

‘Buffer The buffer will contain the current MLI default 
prefix. The prefix consists of one byte of length 
followed by up to 63 characters of prefix. If the 
length is zero, the prefix is null. Otherwise, the 
prefix starts and ends with a slash. 

Return Code $00 —Noerrors 


$04 — Parameter count is not $01 
$56 — Bad buffer address (check system 
memory bit map) 





FUNCTION 


This function locates a file on a volume and sets 
up internal control! blocks (a File Control 
Bloek—F CB, and a Volume Control Block—VCB) 
to allow the user to read or write it. A reference 
number (from 1 to 8) is assigned by the MLI to 
the open file for future identification. (The 
reference number uniquely identifies the FCB 
which is being used with the file.) The current 
position for reading or writing is set to zero 
(start of the file). At most, eight files may be 
open at one time. More than one OPEN may be 
issued to the same file if the file’s access is 
WRITE disabled (read-only file). 

Once a file is opened, it should always be 
closed (using the MLI CLOSE cal]). This is to 
permit the MLI to release the reference number 
for use by other OPENs. In addition, the MLI 
keeps a count of the number of files which are 
open on a volume. If the diskette is switched 
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while files are open, error return codes are 
produced. 

A directory file may also be opened (for 
READs only). When accessing a directory, do 
not make assumptions about the length of an 
entry or the number of entries per block—use 
the fields in the directory header which are 
provided for this purpose. This will help to 
insure that your program will work for future 
releases of ProDOS. A directory file may be read 
only, not written. 


PARAMETER LIST FORMAT 













+0 
Par ADDRESS OF 
PATHNAME 
. ADDRESS OF 
3i+4 FILE BUFFER 
= REFERENCE 


NUMBER 





REQUIRED INPUTS 


+0 Parameter count (3 parameters in list). 

+1/+2 Address (LO/HI) of pathname buffer for file. 
The pathname buffer consists of one byte of 
length followed by 1 to 63 characters of name. If 
the first character is a “/”, the name is 
considered to be fully qualified. If not, the 
current default prefix is added to the name by 
ProDOS. 
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+3/+4 


$BF94 


Address (LO/HI) of a 1024-byte file buffer, 
provided by the caller in his memory, to be used 
by the MLI while the file is open. The buffer 
must begin on an even page boundary (LO 
portion of address must be zero). The MLI uses 
the buffer to hold the current data block and the 
current index block respectively. Its contents 
need not be intitialized by the caller. It should 
not be tampered with by the caller while the file 
remains open. 

The LEVEL byte in the System Global Page 
may be set to indicate the level of this OPEN. Ifa 
subsequent CLOSE is issued with a REF NUM 
of zero, then all files of a given level or higher 
will be closed. This feature is handy in that it 
allows group CLOSEs on user-defined classes of 
files. Normally, LEVEL is set to zero. 


RETURNED VALUES 


+5 


Return Code 


A reference number assigned to this open file by 
the MLI (from $01 to $08). The caller should 
make a note of this number and use it in all 
future references to this open file. A reference 
number is used to identify open files instead of 
the pathname since it is possible to maintain 
multiple “opens” on the same read-only file. 


$00 —Noerrors 

$04 — Parameter count is not $038 

$27 —I/Oerror 

$40 — Pathname has invalid syntax 

$42 —Eight files are already open 

$44 —Path to file’s subdirectory is bad 

$45 — Volume directory not found 

$46 — File not found in specified directory 

$4B — Bad storage type 

$50 — File already open (WRITE enabled) 

$53 — Parameter value out of range (REF 
NUM) 

$56 — Bad buffer address (check system 
memory bit map) 

$5A — Damaged disk freespace bit map 
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FUNCTION 


A file may be read as either a continuous stream 
of bytes or as a collection of lines, terminated by 
“newline” characters (such as a RETURN 
character). When a file is first opened, the 
former assumption is made. To enable the line by 
line mode, the NEWLINE function may be 
invoked, specifying the end of line character to 
be used. All future READ operations on the 
specified open file will be terminated either 
when a newline character is detected, or when 
the read length is exhausted (or at end of file). 


PARAMETER LIST FORMAT 


REQUIRED INPUTS 


+0 
+1 


+2 


+0 

“4 REFERENCE 
NUMBER 

+2 

3 NEWLINE 


CHARACTER 





Parameter count (3 parameters in list). 
Reference number for an open file as returned 
by OPEN. 

AND mask. The value given here is logically 
ANDed with the contents of each byte read 
before a comparison is made with the 
NEWLINE character given in +3. If the AND 
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mask is zero, then the line by line mode is 
disabled and the continuous byte stream mode is 
enabled. If a mask of $F F is given, the 
NEWLINE character must exactly match what 
is read. Other values for the AND mask allow 
“don’t care” bits. For example, $7F allows the 
MSB to be either on or off without affecting the 
comparison (e.g. $0D or $8D will both be treated 
as newline if $0D is the NEWLINE character 
and the AND mask is $7F). 

+3 The actual value of the NEWLINE character. 
Normally, when line by line mode is used, this is 
should be set to $0D. Note that if the AND mask 
is $00, this character is ignored (even if it is also 
$00; if $00 is to be the newline character, set the 
AND mask to $F F). 


RETURNED VALUES 
Return Code $00 —Noerrors 
$04 —- Parameter count is not $03 
$48 —Invalid reference number 









$CA READ: 
) NE OR MORE BYTES FROM AN OPEN FILE 


FUNCTION This function reads a number of bytes, starting 
at the current file position in an open file. The 
number of bytes read depends upon the length 
requested by the caller, whether or not a newline 
character has been set (see the $C9 function call), 
and whether the end of file is reached during the 
read. The current file position is updated to point 
to the byte following the last byte read. 

In general, read operations will be much more 
efficient if the amount of data transferred 
exceeds a block (512 bytes). Special “direct read” 
code exists within the MLI to prevent “double 
buffering” and allow direct reads to the caller’s 
buffer without going through the I/O buffer 
attached to the file. This fast access is only used 
when whole blocks may be read at a time. Use of 
the NEWLINE feature automatically disables 
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“direct reads.” (NOTE: It is this “direct read” 
feature which makes ProDOS I/O faster than 
Apple DOS.) 

Note that, once a file is opened, no check is 
made by the MLI that the user has not switched 
diskette volumes in the drive. If this occurs, it is 
possible to read random portions of the new 
diskette volume! If the programmer is issuing a 
READ after a period of disk inactivity, it is 
recommended that a ONLINE call ($C5) be 
issued to make sure that the same diskette is still 
in the drive. 


PARAMETER LIST FORMAT 


+0 


4 


+2/+3 


+4/+5 


+6/+7 


REQUIRED INPUTS 
+0 


+] 


+2/+3 










REFERENCE 
NUMBER 





ADDRESS OF 
DATA BUFFER 


REQUESTED 
LENGTH 





ACTUAL 
LENGTH 


Parameter count (4 parameters in list). 
Reference number for an open file as returned 
by OPEN. 

Address (LO/HI) of a sufficiently large buffer 
provided by the caller into which the data will be 
read. This buffer should not be confused with the 


+4/+5 
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“file buffer” passed to OPEN which is separate, 
and should not be used by the caller’s program. 
Maximum number (LO/HI) of bytes of data to 
read. This is usually the size of the data buffer. If 
lines are being read, make sure this value is as 
large as the longest line, including the end of line 
character itself. 


RETURNED VALUES 


+6/+7 


Return Code 


Actual number (LO/HI) of bytes placed in the 

caller’s data buffer by the MLI. This value will 

differ from the requested length in +4/+5 if a 

newline character was found, if the end of the 

file was reached, or if an error occurred during 

the read operation. If a newline character 

terminated the read, this length will include the 

newline character itself. If the read began at the 

end of file position, this field is set to zero, and 

the end of file return code ($4C) is placed in the 

A register. 

$00 —Noerrors 

$04 — Parameter count is not $04 

$27 —I/Oerror 

$43 — Invalid reference number 

$4C — Atend of file, nothing was read 

$4E — Access refused: Read bit not enabled 

$56 — Bad buffer address (check System 
memory bit map) 

$5A — Damaged disk freespace bit map 


$CB WRITE: 


WRITE ONE OR MORE BYTES TO AN OPEN FILE 


FUNCTION 


This function writes a number of bytes to disk, 
starting at the current file position in an open 
file. You may not write toa directory. The 
current file position is updated to point to the 
byte following the last byte written. The end of 
file mark is moved if necessary, and new data 
and/or index blocks are allocated to the file as 
necessary. In the interest of efficiency, the data 
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may or may not be written to disk at this time. 
As much as one block’s worth (512 bytes) may 
remain in the file buffer to be written later when 
the block is filled, the file is closed or flushed, or 
when the file position is changed. For this 
reason, it is important to close all files before 
powering off the machine. 

Note that, once a file is opened, no check is 
made by the MLI that the user has not switched 
diskette volumes in the drive. If this occurs, it is 
possible to write on random portions of the new 
diskette volume! If the programmer is issuing a 
WRITE after a period of disk inactivity, it is 
recommended that a RETURN ONLINE 
VOLUMES call ($C5) be issued to make sure 
that the same diskette is still in the drive. 

Note that there is no “direct write” feature 
similar to the “direct read” feature described 
under the READ MLI call. 


PARAMETER LIST FORMAT 


+0 


1 


+2/+3 


+4/+5 


+6/+7 





REFERENCE 
NUMBER 










ADDRESS OF 
DATA BUFFER 







REQUESTED 
LENGTH 





ACTUAL 
LENGTH 
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REQUIRED INPUTS 
+0 Parameter count (4 parameters in list). 
+1 Reference number for an open file as returned 
by OPEN. 
+2/+3 Address (LO/HI) of the data to be written to 
disk. This buffer should not be confused with the 
“file buffer” passed to OPEN which is separate, 
and should not be used by the caller’s program. 
+4/+5 Number (LO/HID) of bytes of data to write from 
the data buffer. 


RETURNED VALUES 
+6/+7 Actual number of bytes written. Unless an error 

occurs during the operation, this field should 
match the requested length in +4/+5. 

Return Code $00 —Noerrors 
$04 — Parameter count is not $04 
$27 —I/Oerror 
$2B — Disk is write protected 
$43 — Invalid reference number 
$48 — Disk full 
$4E — Access refused: WRITE bit not enabled 
$56 — Bad buffer address (check System 

memory bit map) 

$5A — Damaged disk freespace bit map 








os SOG. GEOSE ee 
2 OPEN FILE(S), FLUSHING BUFFERS 


FUNCTION For aspecific open file, this function flushes any 
data which has not yet actually gone to disk from 
the file buffer, releases the file buffer to the 
caller for reuse, sets the BACKUP bit in the 
ACCESS flags for the file, updates the directory 
entry for the file with block count, etc., and frees 
the reference number and File Control Block 
(FCB) for use with a later OPEN. Each OPEN 
must have a corresponding CLOSE. If a non- 
specific call is made (REFNUM = 0), all open 
files at the current LEVEL ($BF94) or higher 
are closed. 
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PARAMETER LIST FORMAT 


r REFERENCE 
NUMBER 





REQUIRED INPUTS 

+0 Parameter count (1 parameter in list). 

+1 Reference number for an open file as returned 
by OPEN or $00 if all files at the current level or 
higher are to be closed. If a multiple file request 
is made and an error occurs on one file, this does 
not prevent the MLI from attempting to 
complete the close operation for any other files. 
If multiple errors occur, only the last error 
return code is passed back to the caller. 

$BF94 Current file LEVEL in the System Global Page. 

If set to $00 before this call, all open files are 
closed. 


RETURNED VALUES 
Return Code $00 —Noerrors 
$04 — Parameter count is not $01 
$27 —1/O error 
$2B — Disk is write protected 
$43 —Invalid reference number 
$5A — Damaged disk freespace bit map 





- $CD FLUSH: 
USH ALL WRITE BUFFERS FOR FILES 








FUNCTION _ For aspecific open file, this function flushes any 
data which has not yet actually gone to disk from 
the file buffer, updates the directory entry for 
the file, and sets the BACKUP bit in the 
ACCESS flags for the file (if data was written). 
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If no write operations have occurred, then the 
FLUSH call is ignored. If a non-specific call is 
made (REFNUM = 0), all open files at the 
current LEVEL ($BF94) or higher are flushed. 
The flush call is useful when it is desirable to 
force write data out to disk before a long period 
of inactivity in case of power loss or other 
disasters. 


PARAMETER LIST FORMAT 


REQUIRED INPUTS 
+0 
+1 


$BF94 


+0 


4 REFERENCE 
NUMBER 





Parameter count (1 parameter in list). 
Reference number for an open file as returned 
by OPEN, or $00 if all files at the current level 
or higher are to be flushed. If a multiple file 
request is made and an error occurs on one file, 
this does not prevent the MLI from attempting 
to complete the flush operation for any other 
files. If multiple errors occur, only the last error 
return code is passed back to the caller. 

Current file LEVEL in the System Global Page. 
If set to $00 before this call, all open files are 
flushed. 


RETURNED VALUES 


Return.Code 


$00 —Noerrors 

$04 — Parameter count is not $01 

$27 —I/Oerror 

$2B — Disk is write protected 

$48 — Invalid reference number 

$5A — Damaged disk freespace bit map 
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FUNCTION 


When a file is first opened, the MLI establishes a 
“file position” at which reading or writing will 
occur at the beginning of the file (zero). As data 
is read or written, the file position is moved to 
allow sequential access to the file. This file 
position describes the relative byte offset to the 
next byte in the file to be accessed. If random 
access to a file is desired, the caller may use this 
function to change the position to another 
location in the file before issuing a READ or 
WRITE eall. If the file position is moved to an 
area of the file where no data exists (i.e. an area 
which has never been written), new data and/or 
index blocks will be allocated when the next 
WRITE call is made. This function may be used 
in conjunction with the GET_EOF call ($D1) to 
append data to the end of a file. 


PARAMETER LIST FORMAT 


+0 


+1 


+2/+3/+4 


REQUIRED INPUTS 
+0 
+1 


+2/+3/+4 


REFERENCE 
NUMBER 






NEW FILE POSITION 






Parameter count (2 parameters in list). 
Reference number for an open file as returned 
by OPEN. 

The new file position to be set. This is a 3-byte 
number (least significant byte first, most 
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significant byte last) representing the byte offset 
into the file. The position of the first byte in a file 
is zero. The position may not exceed the current 
end of file position. 


RETURNED VALUES 


Return Code $00 —Noerrors 
$04 — Parameter count is not $02 
$43 —Invalid reference number 
$4D — File position beyond end of file 
$5A — Damaged disk freespace bit map 





FUNCTION Whenafile is first opened, the MLI establishes a 
“file position” at which reading or writing will 
occur at the beginning of the file (zero). As data 
is read or written, the file position is moved to 
allow sequential access to the file. This file 
position describes the relative byte offset to the 
next byte in the file to be accessed. This function 
will return the current value of the file position. 


PARAMETER LIST FORMAT 


+0 


REFERENCE 


a NUMBER 






+2/4+3/+4 FILE POSITION 
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REQUIRED INPUTS 


+0 
+1 


RETURNED VALUES 


+2/+3/+4 


Return Code 


Parameter count (2 parameters in list). 
Reference number for an open file as returned 
by OPEN. 


The current file position value. This is a 3-byte 
number (least significant byte first, most 
significant byte last) representing the byte offset 
into the file of the next byte to be read or written. 
The position of the first byte in a file is zero. 

$00 —Noerrors 

$04 — Parameter count is not $02 

$48 —Invalid reference number 


$DO0 SET_EOF: 


CHANGE END OF FILE POSITION OF AN OPEN FILE 


FUNCTION 


This function changes the end of file mark (or 
file size). It is not normally necessary to change 
the end of file mark since the WRITE function 
will automatically extend the EOF mark as new 
data is written to the end of the file. This 
function is useful, however, to truncate a file or 
to allow random positioning within a very large 
sparse file. If the new end of file position passed 
by the caller is less than the old one, the file is 
truncated and excess data and index blocks are 
freed for reuse by the system. If it exceeds or 
equals the old value, no new blocks will be 
allocated until they are needed ina WRITE 
operation. If the new end of file would leave the 
current file position outside the limits of the file, 
it is forced back to the new end of file position. 
The EOF mark of a directory file may not be 
changed with SET. EOF. Note that the file size 
does not necessarily represent the amount of disk 
space the file requires, since the file may be 
sparse (see Chapter 4). 
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PARAMETER LIST FORMAT 












+0 

a | "Ege 
42/43/44 POSITIO N 
REQUIRED INPUTS 


+0 Parameter count (2 parameters in list). 

+1 Reference number for an open file as returned 
by OPEN. 

+2/+8/+4 The new end of file position. This is a 3-byte 

number (least significant byte first, most 
significant byte last) representing the byte offset 
into the file of the last byte plus one. The position 
of the first byte in the file is zero (the EOF of an 
empty file). 


RETURNED VALUES 

Return Code $00 —Noerrors 
$04 — Parameter count is not $02 
$27 —1/Oerror 
$43 — Invalid reference number 
$4D — Position is too large for volume 
$4E — Access refused: WRITE bit not enabled 
$5A — Damaged disk freespace bit map 





Snare $D1 GET_EOF: | os 
RETURN) END OF FILE POSITION OF AN OPEN FILE, 


FUNCTION This function returns the value of the end of file 
mark for an open file. GET_EOF may be used to 
determine the size of a sequential file or to find 
the end of a file so that data may be appended to 


6-56 Beneath Apple ProDOS 


it. GET_EOF for a directory file will return the 
number of blocks used multiplied by 512 bytes. 
Note that the file size does not necessarily 
represent the amount of disk space the file 
requires, since the file may be sparse (see 
Chapter 4). 


PARAMETER LIST FORMAT 


+0 





REFERENCE 
NUMBER 





+1 







EOF 


sear POSITION 






REQUIRED INPUTS 


+0 Parameter count (2 parameters in list). 
+1 Reference number for an open file as returned 
by OPEN. 


RETURNED VALUES 


+2/+3/+4 Thecurrent end of file position. This is a 3-byte 
number (least significant byte first, most 
significant byte last) representing the byte offset 
into the file of the last byte plus one. The position 
of the first byte in the file is zero (the EOF of an 
empty file). 


Return Code $00 —Noerrors 
$04 — Parameter count is not $02 
$43 — Invalid reference number 
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NGE OPEN FILE'S BUFFER ADDRES 


FUNCTION This function allows the caller to move an open 
file’s file buffer to another location in memory. 
Since READ and WRITE references are by 
Reference Number, the MLI must memorize the 
location of the file buffer at OPEN time. If the 
buffer must be moved, this call allows the 
programmer to inform the MLI and allow it to 
move the contents of the buffer to the new 
location. The system memory bit map is updated 
to reflect the change. 


PARAMETER LIST FORMAT 


+0 





REFERENCE 


+1 
NUMBER 





NEW ADDRESS OF 
FILE BUFFER 





+2/+3 






REQUIRED INPUTS 

+0 Parameter count (2 parameters in list). 

+1 Reference number for an open file as returned 
by OPEN. 

+2/+3 The address (LO/HI) of a new 1024-byte location 

in which the MLI may maintain the open file’s 
buffer. It must be on an even page boundary (LO 
byte of address is zero) and not be allocated by 
the MLI to any open file. The contents of the 
current file buffer are transferred to this new 
area, and the old buffer is marked released in 
the System Global Page memory bit map. 
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RETURNED VALUES 
Return Code $00 —Noerrors 
$04 —Parameter count is not $02 
$43 — Invalid reference number 
$56 — Buffer already in use by MLI 





FUNCTION This function returns the address of the file 
buffer associated with an open file to the caller. 


PARAMETER LIST FORMAT 








+0 
4 REFERENCE 
NUMBER 
pe FILEBUFFER 
REQUIRED INPUTS 


+0 Parameter count (2 parameters in list). 
+1 Reference number for an open file as returned 
by OPEN. 


RETURNED VALUES 
+2/+3 The address (LO/HI) of the 1024-byte file buffer 
in use by the MLI for this file. 
Return Code $00 —Noerrors 
$04 — Parameter count is not $02 
$43 — Invalid reference number 
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MLI ERROR CODES 
$00 Noerror occurred. Operation completed successfully. 
$01 Invalid MLI function code number. 


$04 Incorrect parameter count in parameter list for the function 
code used. 


$25 The ProDOS interrupt handler vector table is full. There 
are already four addresses stored there. 


$27 A device driver reported an Input/Output error on the 
media. This could be anything from the diskette drive door 
being open toa real error on the surface of the diskette. 


$28 Nodevice is connected for the unit number given. This can 
happen if no identifiable controller ROM was present in the 
indicated slot. 


$2B Anattempt was made to write to the disk, but it was write 
protected. Remove the tape over the write-protect notch if 
you wish to write on this diskette. 


$2E Inthe process of performing an ONLINE call, the MLI 
discovered that a diskette for which there were open files 
had been removed from its drive and replaced by another 
volume. Since no check is made when writing to an open file, 
it is possible that some blocks on the new volume have been 
damaged. 


$40 The pathname has invalid syntax. Check to make sure the 
first byte is a count of the number of characters that follow. 
Also, be sure that each sub-level index begins with an 
alphabetic character.and that each level is separated from 
the next by aslash (/). 

$42 Eight files are open and there is no more room in the MLI’s 
File Control Block (FCB) table for another open file. If you 
didn’t expect any files to be open, set the LEVEL to zero and 
issue a global CLOSE. 

$48 The reference number passed in the parameter list does not 
denote an open file. Make sure that the OPEN call was 
successful before issuing other calls by reference number. 

$44 The pathname supplied could not be followed to the final 
directory. One or more of the subordinate directories in the 
path did not exist. 

$45 The volume indicated by the pathname is not currently 
mounted on any drive. 
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$46 


$47 


$48 


$49 


$4A 


$4B 


$4C 


$4D 


$4E 


$50 


$51 
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The file indicated by the last name in the pathname was not 
found in the final directory. 


A CREATE or RENAME was attempted and the file 
named already exists. To perform the operation would 
create a duplicate entry in the directory. 


An attempt was made to find one or more free disk blocks (to 
extend a directory, add a new data block for a file, etc.), but 
the Volume Bit Map indicates that the diskette is now full. 


An attempt was made to CREATE another file in the 
Volume Directory, but there are no free entries. Unlike 
subdirectories, the Volume Directory is of a fixed size (51 
entries) and cannot be extended. 


An earlier version of the ProDOS MLI is being used to read 
a file which was created with a later version. The older MLI 
cannot handle this file properly. Use a newer version of 
ProDOS. This error can also occur if the final subdirectory 
header has an improper format. The byte at +$14 in the 
subdirectory key block (reserved bytes) must contain 5 and 
only 5 one bits (it is usually $75). 


The storage type of a file is not one of the storage types 
currently supported by this version of ProDOS. Currently, 
only Seedlings ($01), Saplings ($02), Trees ($03) and 
Directories ($0D) are supported. 

A READ operation was attempted and the current file 
position is at the End of File mark. No data was transferred. 


An attempt was made to move the file position past the End 
of File mark. If this position is desired, first move the EOF 
mark. 


Anerror occurred having to do with the ACCESS bits for a 
file. Usually this means you attempted to WRITE toa write 
protected file, or you attempted to DESTROY or RENAME 
a locked file. You can also get this error if any of the reserved 
bits are ones for the ACCESS byte of a SET_FILE_INFO 
call. 


An attempt was made to OPEN, RENAME, or DESTROY 
a previously OPENed file. Multiple OPENs are only 
allowed if the files WRITE ACCESS bit is off (write 
disabled). 


When searching a directory, it was determined that the 
count of active file entries in the directory header was larger 
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$52 


$53 


$55 


$56 


$57 


$5A 


than the number of entries actually encountered. The 
directory is damaged and some file entries may be lost. 


The disk volume which was accessed is nota ProDOS disk. 
The criteria for determining whether a volume is a ProDOS 
formatted volume are: the first two bytes of the Volume 
Directory key block must be zero (previous block pointer); 
and the byte at offset 4 into the Volume Directory key block 
must be $E or $F (storage type). 

One or more of the values in the parameter list is not within 
its acceptable range. For example, an interrupt handler 
address of $0000 was passed to ALLOC_INTERRUPT. 


At most, only eight “mounted” volumes may be known to 
ProDOS at one time. Usually this is no problem since only 
eight files may be open at a time. However, if a single file is 
open on each of eight different volumes and an ONLINE call 
is made requesting the volume name mounted on a ninth 
device, this error will result. 


The address of the I/O file buffer passed to OPEN or 
SET_BUF is invalid. The buffer overlaps a previously 
assigned buffer, memory below $200, or ProDOS itself. The 
buffer must be in the caller’s memory, and all four of its 
pages must be marked free in the System Global Page 
memory bit map. 

In the process of mounting volumes and recording their 
names in the Volume Control Block (VCB) table, the MLI 
discovered two volumes with the same name. Since all file 
references must be made by volume name and not necessarily 
by slot and drive, this condition is not permitted. 

The Volume Bit Map describing the freespace on the volume 
is damaged. A one bit was found, indicating a free block, for 
a block outside the legal extent of the volume (for a block 
number beyond the end of the volume). 


PASSING COMMAND LINES TO THE BASIC INTERPRETER 


For machine language programs running under the ProDOS 
BASIC Interpreter (BI), an interface is provided to allow 
execution of command lines created by a program, as if they had 
been entered from the keyboard. This is the highest level and 
perhaps the easiest to use ProDOS interface. Through it, a 
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machine language program may easily produce CATALOG 
listings, DELETE or RENAME files, ete. 

To call the BI command handler, place the command string in 
the monitor GETLN line input buffer at $200. The line may be up 
to 255 characters in length, and must be followed by a carriage 
return character ($8D). The most significant bit of each character 
should be set, and all alphabetics should be in upper case. Once this 
has been done, call $BE03 in the BI’s Global Page (JSR $BE03). 

If anerror occurs, a 1-byte BI error code will be placed in 
$BEOF. Possible codes are listed in Table 6.6. 


Table 6.6 BASIC Interpreter Error Codes 


CODE | MESSAGE 


Noerror 

Not used 

RANGE ERROR 

NO DEVICE CONNECTED 
WRITE PROTECTED 
END OF DATA 

PATH NOT FOUND 

Not used 

I/O ERROR 

DISK FULL 

FILE LOCKED 

INVALID PARAMETER 
RAM TOO LARGE 

FILE TYPE MISMATCH 
PROGRAM TOO LARGE 
NOT DIRECT COMMAND 
SYNTAX ERROR 
DIRECTORY FULL 

FILE NOT OPEN 
DUPLICATE FILE NAME 
FILE BUSY 

FILE(S) STILLOPEN 





If you wish to print an error message, you need not have a table 
of messages similar to the above. Instead, place the error number 
in the A register and call SRBEOC (JSR $BEOC). 

Keep in mind that, unless the machine language program was 
called by a BASIC program, only direct commands may be issued 
(as if from the keyboard). BASIC file commands such as OPEN, 
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READ, WRITE, APPEND, and POSITION will result ina NOT 
DIRECT COMMAND error. Under Apple DOS, commands could 
be printed with a control-D from an assembly language program, 
exactly as with BASIC programs. Under ProDOS, this method no 
longer works. This is because the intercepts used for the “control-D 
interface” are no longer in the screen output vector, but are now in 
the Applesoft trace facility, which, of course, isn’t active when 
your machine language program is running. 


COMMON ALGORITHMS 
Given below are several pieces of code which may be used when 
working with ProDOS. 


IS ProDOS ACTIVE? 


The following series of instructions should be used prior to 
attempting to call the ProDOS MLI. 


LDA SBF@@ GET MLI VECTOR JMP 
CMP #S4C IS If A JUMP? 
BNE NOPRODS NO, PRODOS NOT ACTIVE 


WHAT KIND OF MACHINE IS THIS? 


This code will test to determine what type of Apple is running 
the program. 


LDA #$@8 
BIT SBF98 TEST MACHID FROM GLOBAL PAGE 
BEQ OLDSYS OLDER SYSTEM 
BPL UNKN FUTURE SYSTEM - UNKNOWN 
BYC APIIC IT'S AN APPLE LIC 
BVS UNKN OTHERWISE, UNKNOWN 
OLDSYS BMI EOR3 EITHER A IIE or a III 
BVC APII IT'S AN APPLE II 
BVS APIIP IT'S AN APPLE II+ 
EOR3 BVS APIII IT'S AN APPLE III 
oe OTHERWISE ITS AN APPLE IIE 


HOW MUCH MEMORY IS IN THIS MACHINE? 
This code will determine whether the Apple has 48K, 64K or 
128K of RAM. 


LDA $BF98 GET MACHID FROM GLOBAL PAGE 
ASL A MOVE BITS TO TEST POSITION 
ASL A 

BPL SMLMEM 48K 

ASL A 


BVS MEM128 128K 
eee OTHERWISE 64K 
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GIVEN A PAGE NUMBER, SEE IF IT IS FREE 


This code examines ProDOS’s memory bit map to see if a page is 
marked free. If so, the page is marked as allocated. 


BITMAP EQU SBF58 SEE PAGE 8-6 
LDA #PAGE GET PAGE NUMBER (MSB OF ADDR) 
JSR LOCATE LOCATE ITS BIT IN BITMAP 
AND BITMAP,Y IS IT ALLOCATED? 
BNE INUSE YES, CAN'T TOUCH IT 
TXA PUT BIT PATTERN IN ACCUM 


ORA BITMAP,Y MARK THIS PAGE AS IN USE 
STA BITMAP,Y UPDATE MAP 
eee WE'VE GOT IT NOW 


LOCATE PHA SAVE PAGE NUMBER 
AND #$97 ISOLATE BIT POSITION 
TAY THIS IS INDEX INTO MASK TABLE 
LDX BITMASK,Y PUT PROPER BIT PATTERN IN X 
PLA RESTORE PAGE NUMBER 
LSR A DIVIDE PAGE BY 8 
LSR A 
LSR A 
TAY Y-REG IS OFFSET INTO BITMAP 
TXA PUT BIT PATTERN IN ACCUM 
RTS DONE 


BITMASK DFB $86,$48,$2@,$1@ BIT MASK PATTERNS 
DFB $88,$04,$02,$@1 
IS ABASIC PROGRAM RUNNING? 


This code will allow your machine language program to 
determine whether it was called by a BASIC program. 


LDA $BE42 CHECK BI'S STATE 
BEQ NOTRUN IN IMMEDIATE MODE 
eee ELSE, BASIC PROGRAM RUNNING 


SETTING UP YOUR OWN RESET VECTOR 
The code below will set up a user-defined RESET handler. 


LDA #>RESRTN SET UP LSB 

STA $3F2 

LDA #<RESRTN SET UP MSB 

STA $3F3 

EOR #SA5 MAKE POWER-UP BYTE 
STA $3F4 

eee RESET VECTOR READY 


RESRTN) ... RESET HANDLER ROUTINE 
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ACTIVATE A PRINTER OR OTHER PERIPHERAL 

To activate a printer or other peripheral driver under the 
ProDOS BASIC Interpreter, do not modify the vectors in zero 
page (CSWL/CSWH or KSWL/KSWH). Doing so will “disconnect” 
the interpreter and prevent it from intercepting command lines. 
Instead, store the address of the peripheral driver in BI Global 
Page in the VECTOUT ($BE30) or VECTIN ($BE32) words. The 
following code will start up a printer in Slot 1. 


LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 


SBE3@ 
OLDVEC 
SBE31 
OLDVECt1 
#$00 
SBE3@ 
#SC1 
SBE31 


OLDVEC 
SBE3@ 
OLDVEC+1 
$BE31 


SAVE ORIGINAL CONTENTS OF VECTOUT 
IN MY MEMORY SO I CAN TURN THE 
PRINTER OFF WHEN I'M THRU 


PLACE $C168 IN VECTOUT 


BEGIN PRINTING VIA COUT 


RESTORE PREVIOUS OUTPUT VECTOR 


CHAPTER 7 


CUSTOMIZING ProDOS 


SYSTEM PROGRAMMING WITH ProDOS 


Apple has provided a number of customizing interfaces to Pro- 
DOS which allow a programmer to tailor the operation of the sys- 
tem to his specific application needs. These interfaces are 
considered “safe” and acceptable when working with ProDOS. 

Before discussing specific system programming considerations, 
it is important to understand how ProDOS uses memory and what 
areas are reserved for its use versus those available for applica- 
tions programs. Referring to Figure 7.1, the following areas of 
memory are officially “owned” by the ProDOS Kernel: $D000- 
$F FFF in the language card (primary $D000-$DF FF bank); 
$BF00-$BFFF; Zero page locations $3A-$4F; and part of the 
second 4K bank of the language card (starting at $D100). The rest 
of this 4K bank is reserved for the QUIT eode driver and future 
uses. The ProDOS Kernel also reserves portions of auxiliary 
memory (128K) for future use—namely, the same locations it uses 
in main memory, zero page locations $80-$F F, and locations $200- 
$3FF. Apple’s future plans for these memory areas include net- 
working and menu managers, so if you use them you do so at your 
own risk. Ina 128K machine, ProDOS currently sets up an elec- 
tronic “RAM drive” volume in the auxiliary memory. At present, 
this volume encompasses most of the auxiliary 64K. In the future, 
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its size may be reduced to accommodate enhancements as men- 
tioned above. You can use the auxiliary memory for your own 
applications if you disable the /RAM device driver (see instruc- 
tions later in this chapter). If the BASIC Interpreter is used, an 
additional area of memory from $9600-$BEFF is allocated to its 
use. $3D0-$3FF is used as a system vector area as defined by the 
Apple IT Reference Manual for the Ile Only. 

Note that ProDOS routines, including the clock driver, make 
heavy use of $200-$2FF, the monitor GETLN input line buffer. If 
your programs use this area you should not depend upon it across 
ProDOS system calls. You should also be aware of the fact that the 
MLI cannot be called from memory in the auxiliary bank, and 
that memory outside the area between $200 and $BEFF in the 
main RAM bank may not be used for buffers passed to the MLI. 





Pro DOS CAN BE TAILORED TO SUIT SPECIFIC NEEDS. 
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MAIN MEMORY AUXILIARY MEMORY 


SFEFF 


$F000 


$E000 


$D100 


$D000 


$C000 
sBF0O 4 











SYSTEM 
GLOBAL 


$B000 PAGE 


$0800 







SCREEN 





$0400 
aa se 
$0200 MMMM —— 3 ETLN $0200 






ae 
$0000 (-— 77mg STACK ~—s soo00 [77777778 





ZERO PAGE USE. $3A S4F ZERO PAGE USE: $80—SFF — 


ON ZZ lil 


RESERV ‘RAM AVAILABLE 





Figure 7.4 ProDOS Memory Usage 
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INSTALLING A PROGRAM BETWEEN THE BI AND ITS 
BUFFERS 


Once ina while it is useful to find a “safe” place in memory to put 
a machine language program (a printer driver, or external com- 
mand handler, perhaps) where BASIC and ProDOS will never 
walk over it. If the program is less than 200 bytes long, $300 is a 
good choice. For larger programs, it is usually better to “tuck” the 
program in between the ProDOS BASIC Interpreter and its file 
I/O buffers. The program need not be relocatable, since the BI will 
always be in the same place in memory, and the program can be 
placed at a fixed location just beneath it (see Figure 5.1). More 
than one program may be “tucked” in this area, but this may 
require one or more of them to be relocated, depending upon the 
order in which they are loaded. 

To request space for a program, you must execute a call to the 
BI’s buffer allocation subroutine using a vector in the BI Global 
Page. You may request a buffer of any size as long as it is an even 
multiple of pages (one page is 256 bytes). When called, the buffer 
allocation routine relocates any open file buffers as well as its Gen- 
eral Purpose Buffer downward in memory, lowering Applesoft’s 
HIMEM pointer as necessary, and returns the address of the first 
page in the new buffer. The new buffer will be placed directly 
below $9A00. Subsequent calls to the buffer allocation routine will 
cause allocations of buffers below earlier ones. The BI file buffers 
will always be lower in memory than any externally allocated 
buffers. When you are finished with all of the buffers you have 
allocated, you may free all of them with a single call. There is no 
provision for freeing individual buffers. 

To allocate a buffer, invoke the following subroutine: 


GBUFF LDA #4 ALLOCATE 4 PAGES (1024 BYTES) 
JSR SBEF5 CALL GETBUFR 
BCS ERROR DID AN ERROR OCCUR? 
STA BUFMSB STORE BUFFER ADDRESS MSB 
LDA #6 
STA BUFLSB STORE BUFFER ADDRESS LSB 


RTS ALL DONE 
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To free all buffers you have allocated: 
FBUFFS JSR S$BEF8 CALL FREEBUFR 


Note that you may allocate as many buffers as you wish using the 
GBUFF subroutine, but that a single call to FBUFFS frees all 
buffers. 


ADDING YOUR OWN COMMANDS TO THE ProDOS BASIC 
INTERPRETER 


There exists a well defined interface to allow you to write your 
own command handlers for the ProDOS BASIC Interpreter. Sup- 
pose, for example, that you wish to add a COPY command which 
will accept an input pathname, followed by a comma and an output 
pathname. You can write a handler for such a command in assem- 
bly language, install the handler between the BI and its buffers 
(see the previous section), and then inform the BI of its existence. 
Every time the BI receives a command line it doesn’t recognize, it 
will pass it through to your handler before passing it to Applesoft. 
Note that this implies that your command’s name must be differ- 
ent from any existing ProDOS command name. You may not 
replace or supersede an existing ProDOS command. 


SCROLL UP! 
PRINT OUT! 
GOOD DOS! 
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To install your own command handler, place its entry point 
address in the vector in the BI Global] Page at $BE07 and $BEO8. 
These two bytes are the address portion of a Jump (JMP) instruc- 
tion (EXTERNCMD) which normally points to a Return from 
Subroutine (RTS) instruction within the BI. It is not a good idea to 
assume that this address is pointing to an RTS since someone else’s 
command handler could have been previously installed. To make 
sure you do not “disconnect” an earlier installed command handler 
and that yours is “daisy chained” to it, save the address you find in 
EXTERNCMD + 1 and branch to it from your handler if the com- 
mand line passed is not your command. 

Each time the BI scans a command line and cannot find the 
command name in its table of valid names, it will call your routine. 
Your program should compare the command in the command line 
with yours. The address of the command line is in VPATH1 
($BE6C/$BE6D) in the BI Global Page. The command line con- 
sists of a length byte followed by one or more ASCII characters 
with their most significant bit off. If the command is not yours, 
jump to the next handler (previous contents of $BE07/$BE08) with 
the carry set (SEC) to indicate the command is not yours. If the 
command is yours, there are two options. If the command’s syntax 
is not compatible with other ProDOS commands (i.e. it has non- 
standard operands or keywords), you may immediately begin per- 
forming the function indicated. When the program finishes, it 
should store a zero in PBITS in the BI Global Page ($BE54) to 
indicate no operands are to be parsed, and return (RTS) with the 
earry clear (CLC). In this case, do not JMP to the next handler as 
you would if the command was not yours. If, on the other hand, the 
command has standard ProDOS syntax, you can use the BI’s syn- 
tax scanner to pick off the operands and optional keywords. To do 
this, once you have identified the command as yours, store the 
address of the beginning of your code which will process the com- 
mand (after the syntax scan) in XTERNADDR ($BE50/$BE51) in 
the BI Global Page, store a $00 in XCNUM ($BE58) to indicate 
that this is an external command, and store the length of your 
command name (less one) in XLEN ($BE52) so that the BI will 
know where to start looking for operands. You should also set up 
PBITS (two bytes of flags) in the BI Global Page to describe the 
operands the BI is likely to find on your command. If you havea 
very simple command with only a pathname as an operand, you 
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can set PBITS to $01,$00. If you want the BI to automatically pro- 
vide the prefix of the current volume (default slot, drive) as well as 
allow the S and D keywords, set PBITS to $01,$04. Once you have 
set up XTERNADDR, XCNUM, XLEN, and PBITS, return 
(RTS) to the BI with the carry clear (CLC). When the command 
line has been successfully scanned, contro! will return to your 
handler at the location you indicated in XTERNADDR. If aSYN- 
TAX ERROR occurs, control will not return. When your command 
handler completes its tasks, it may return to the BI withan RTS 
instruction (the carry here is insignificant). Your handler need not 
save or restore any registers. 

An example of a command handler is given in APPENDIX A. 
This program installs a handler between the BI and its buffers, 
and connects it to ProDOS through the the EXTERNCMD vector. 
If the ProDOS user enters the command “TYPE” followed by a 
pathname, the command handler reads the indicated file and 
prints it on the screen. 


DISABLE /RAM VOLUME FOR 128K MACHINES 


If your application needs to use the additional 64K in the 
Extended 80-column Card (or the alternate 64K bank in the IIc) 
for its own purposes, rather than as an electronic disk drive (RAM 
drive), you should disable the /RAM device driver. You might want 
to do this if you plan to use the “double HIRES” graphics feature of 
the Apple Ile and IIc, for example. 

The /RAM device driver is installed by the ProDOS Loader/ 
Relocator when the Kernel is loaded. Part of it resides in the Ker- 
nel itself (from $F F00-$F F7F), and the remainder resides in aux- 
iliary memory at $200-$3FF. Its address is placed in the list of 
device drivers for Slot 3, Drive 2 in the System Global Page. 

One way to avoid conflicts between /RAM and your application 
isto BSAVE adummy file such that its blocks will coincide with 
the area of memory you will be using. If you BSAVE an 8K file to 
/RAM (before any other operations on the /RAM volume), it will 
fall across $2000-$3F FF, the primary HIRES buffer. If you save a 
second 8K file it will fall across $4000-$5F FF, the secondary 
HIRES buffer. This is the easiest way to use “double HIRES” 
graphics while leaving the /RAM volume partially available for 
your use as an electronic disk drive. 
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If you want to totally disable the /RAM device driver, you must 
remove its entry from the System Global Page device driver vector 
list (DEVADR32). You must also remove the device number for 
Slot 3, Drive 2 from the online devices list (DEV LST), and reduce 
the device count (DEVCNT) by one. If you plan to reinstall the 
/RAM volume later, be sure to save the contents of DEVADR32 in 
a safe place so you can later restore it. Note that it is good pro- 
gramming practice to leave /RAM installed upon exiting your 
program so that other applications may use it. Reinstalling /RAM 
erases (“formats”) the volume, so you should not reinstall it upon 
entry to an application which will] be reading files passed via the 
/RAM volume by a previous application. 

The following subroutine will remove the /RAM driver, allowing 
alternate uses of the auxiliary 64K: 


SKP 1 
* START BY CHECKING TO SEE IF /RAM COULD BE THERE 
SKP 1 
REMOVE LDA SBF98 CHECK -MACHID 
AND #$38 ISOLATE MEMORY BITS 
CMP #536 128K? 
BNE NORAM NO — NO AUX MEMORY 
LDA SBF26 
CMP SBF16 IF SLOT 3, DRV 1 <> DRV 2 VECTOR.. 
BNE GOTRAM’ THEN IT'S INSTALLED 
LDA $BF27 
CMP SBF17 
BNE GOTRAM 
NORAM SEC ; INDICATE NO /RAM INSTALLED 
OKXIT RTS 
SKP 1 
= SAVE OLD VECTOR AND REMOVE IT 
SKP 1 
GOTRAM LDA SBF26 SAVE OLD VECTOR CONTENTS 
STA OLDVEC 
LDA $BF27 
STA OLDVEC+1 
LDA SBF16 POINT IT AT "UNINSTALLED DEV" 
STA $BF26 
LDA SBF17 
STA $BF27 
SKP 1 
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DEVLP 


GOTSLT 


OLDVEC 


SQUISH OUT DEVICE NUMBER FROM DEVLST 


SKP 
LDX 
LDA 
AND 
CMP 
BEQ 
DEX 
BPL 
BMI 
LDA 
STA 
INX 
CPX 
BNE 
DEC 
LDA 
STA 
CLC 
BCC 
SKP 
DW 


1 

$BF31 
$BF32,X 
#578 
#$30 
GOTSLT 


DEVLP 
NORAM 
SBF32+1,X 
SBF32,X 


SBF31 
GOTSLT 
$BF31 
#508 
SBF32,X 


OKXIT 
1 
i) 


GET DEVCNT 

PICK UP LAST DEVICE NUM 
ISOLATE SLOT 

SLOT = 3? 

YES, CONTINUE 


CONTINUE SEARCH BACKWARDS 
CAN'T FIND IT IN DEVLST 
GET NEXT NUMBER 

AND MOVE THEM FORWARD 


REACHED LAST ENTRY? 

NO, LOOP 

REDUCE DEVCNT BY 1 

ZERO LAST ENTRY IN TABLE 
BRANCH ALWAYS TAKEN 


OLD VECTOR SAVEAREA 


To reinstall the /RAM driver, execute this subroutine: 


* 


HIMEM 


INSTALL 
INSLP 


ERROR 


INSLP2 


SKP 
SEE 


SKP 


1 


IF SLOT 3 HAS A DRIVER ALREADY 


1 
$73 

1 

$BF31 
S$BF32,X 
#370 
#$30 
INSOUT 


INSLP 
1 


PTR TO BI'S GENERAL PURPOSE BUFFER 


GET DEVCNT 
GET A DEVNUM 
ISOLATE SLOT 
SLOT 3? 

YES, SKIP IT 


KEEP UP THE SEARCH 


RESTORE THE DEVNUM TO THE LIST 


SKP 
LDX 
CPX 
BNE 


LDA 
STA 
DEX 
BNE 
LDA 
STA 
INC 
SKP 


a 
$BF31 
#$6D 
INSLP2 


$BF32-1,X 
$BF32,X 


INSLP2 
#$BO 
$BF32 
$BF31 
1 


GET DEVCNT AGAIN 
DEVICE TABLE FULL? 


YOUR ERROR ROUTINE 
MOVE ALL ENTRIES DOWN 


TO MAKE ROOM AT FRONT 
FOR A NEW ENTRY 


SLOT 3, DRIVE 2 AT TOP OF LIST 
UPDATE DEVCNT 
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* NOW PUT BACK THE DEVICE DRIVER VECTOR 
SKP 1 
LDA OLDVEC FROM PREVIOUSLY SAVED VECTOR 
STA SBF26 
LDA OLDVEC+1 
STA $BF27 
SKP 1 
ba FINALLY, REFORMAT THE /RAM VOLUME 
SKP 1 
LDA SBF32 
STA $43 DEVNUM = SLOT 3, DRIVE 2 
LDA #3 
STA $42 CMD = FORMAT 
LDA HIMEM 512-BYTE BLOCK BUFFER 
STA $44 (PAGE ALIGNED) 
LDA HIMEM+1 WE CAN USE BI'S G.P. BUFFER 
STA $45 (IF BI IS AROUND) 
STA $CO88 SELECT L.C. FOR DRIVER 
JSR RAMDRV GO FORMAT THE VOLUME 
STA $C@81 SELECT MOTHERBOARD ROMS 
INSOUT RTS ; AND EXIT TO CALLER 
RAMDRV JMP (SBF26) <<< JUMP TO /RAM DRIVER >>> 


WRITING YOUR OWN INTERPRETER 


A ProDOS “Interpreter” (also known as a “System Program”) is 
a machine language program which stands between the user and 
the ProDOS MLI, providing a function. An interpreter may be 
executed by the smart RUN command (“—”), may be invoked at 
boot time, or may be executed upon leaving another ProDOS 
interpreter. Interpreters are stored in SYS files on a ProDOS 
volume, and are initially loaded at $2000, although they may 
include code to relocate themselves elsewhere once they begin 
execution. Examples of interpreters are BASIC.SYSTEM (the 
“BI”), FILER, CONVERT, and EDASM.SYSTEM. According to 
convention, an interpreter must be able to pass control to any other 
interpreter when it exits. 

When writing your own interpreter, you must be aware of these 
considerations: 


1. You must BSAVE your interpreter as a “SYS” type file from 
location $2000. If you want your code to execute elsewhere in 
the machine, you may include a front-end which relocates the 
rest of the program (this is.what the BI does). Normally, the 
memory available to you in a 64K system includes $800- 
$BEFF. If you are running in a 48K machine, the ProDOS 
Kernel occupies memory from $9000-$BFFF so you are 
limited to $800-$8F FF for your program. 
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2. If you want your interpreter to be automatically executed as 
the first interpreter when ProDOS boots, you must name it 
“xxxx.SYSTEM”, where xxxx can be any name. It must also 
be the first SYS file using that naming convention to be found 
in the Volume Directory of the boot diskette. 

38. In order to insure correct operation of the interrupt handler in 
the ProDOS Kernel, set the stack register (S) to point to the top 
of the stack page ($F F) upon entry, and do not use more than 
the top three quarters of the stack. The interrupt handler 
assumes that the last item on your stack is stored at $1FF, 
when it makes its determination of whether or not to save part 
of the contents of the stack before invoking an interrupt driver 
routine. 

4, Assoon as your program begins execution, it should set up the 
POWERUP byte in page 3 and three areas in the System 
Global Page as follows. 


S3F4: POWERUP byte 

SBF58: BITMAP (system memory bit map) 

SBFFC: IBAKVER (minimum version of MLI acceptable) 
SBFFD: IVERSION (verSion number of your interpreter) 


When your interpreter gets control, it should first set up the 
RESET vector at $3F2/$3F3 to point to its own RESET 
handler and fix the POWERUP byte at $3F4 accordingly. The 
POWERUP byte should be fixed even if you do not replace the 
RESET handler address (unless you want to reboot on 
RESET). To fix the POWERUP byte, exclusive OR the 
contents of $3F3 with #$A5 and store the result at $3F4. 

A subroutine for checking the system memory bit map was 
given in Chapter 6. Use this to mark those areas of memory 
which your program will use. Do not mark areas which may be 
used for MLI buffers. By doing this, the MLI can keep a 
watchful eye on the execution of your program to prevent 
accidental overlay of your code with buffers. To determine 
what values to use for IBAKVER and IVERSION, examine 
memory in the version of ProDOS you are using for 
development and note the values at $B FFE (KBAKVER) and 
$BFFF (KVERSION). Assemble the values you find there as 
constants into your program, and use these to initialize 
IBAKVER and IVERSION. 
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5. If you wish to use 80 columns, first check the MACHID byte in 
the System Global Page to see if 80 columns are available and 
then call (JSR) $C300. To disable 80-column hardware, load a 
#$15 into the A register and call $C300. Avoid using the Apple 
IIe and IIc 80-column soft switches, because these will not 
work for third party 80-column cards or in an Apple II or 
Apple IT Plus. 

6. When your program is ready to exit, close all open files, 
reinstall the /RAM driver if you disconnected it previously, 
and execute the following code. 


EXIT DEC $3F4 FORCE REBOOT ON RESET 
JSR SBFGOG CALL THE MLI 
DFB $65 QUIT CALL 
DW PARMS 
SKP 1 
PARMS DFB 4 4 PARMS 
DFB @ QUIT TYPE = @ 
DW @ RESERVED 
DFB @ RESERVED 
DW 6 RESERVED 


The MLI will free any memory you have allocated in the 
system bit map. It will then prompt the user for a new prefix 
and pathname for the next interpreter, and will load it and 
execute it. The code which performs these tasks is at $D100- 
$D3FF in the secondary 4K block of the language card. It is 
moved by the MLI to $1000-$12F F before execution. You may 
create your own quit code by replacing the three pages of code 
image in the language card if you wish. 


Customizing ProDOS 7-43 


INSTALLING NEW PERIPHERAL DRIVERS 


If you are writing a driver for a peripheral, such as a printer or 
disk drive, you should be aware of the conventions to which 
ProDOS adheres when examining and calling drivers. 

If your driver is in ROM on the peripheral card itself, it should 
follow the Apple II standards for peripherals as follows. 


FOR NON-DISK DEVICES 


$38 (standard BI 
requirement) 
$18 (standard BI 
requirement) 
$01 (generic signature of 
firmware cards) 
$ci (specific device signature) 
The device signature is made up of two nibbles. “c” defines the 
class of devices as shown below. The second nibble, “i”, is a specific 
device identifier assigned by Apple Computer, Ine. 





reserved 

printer 

joystick or X-Y input device 
serial or parallel card 
modem 

sound or speech device 
clock 

mass storage device 
80-column card 

network or bus interface 


special purpose (other) 
reserved 


$08 (unique device signature 
for the Thunderclock) 

$28 

$58 

$70 
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FOR DISK DEVICES 
ADDRESS | VALUE 
$20 (unique disk device signature) 





$00 
$03 
$3C 







Disk capacity in blocks (non-DISK IT) 

Status bits (non-DISK II) 

Vek removable media 

.1...... interruptable device 

..nn.... number of volumes on device 

.. L... format allowed 

.. 1... write allowed 

wel. read allowed 

Giese 1 status read allowed 

ProF ILE status bits = $47 

$00 = DISK II 

$xx = LSB of Block device driver in ROM 
for non-DISK II ($Csxx). 

ProF ILE hard disk $xx = $EA. 

$xx may not equal $FF. 


If your driver is in RAM (below $C000), and you are invoking it 
using the BASIC Interpreter’s commands PR# A$xxxx or IN# 
A$xxxx, the first byte of your code must be a CLD instruction 
($D8); otherwise, the BI will not recognize your routine as a valid 
driver. If your routine is short, you can place it in the $300-$3EF 
range. If it is longer, you can call the BI’s buffer allocation routine 
(previously covered in this chapter) to place it between the BI and 
its buffers. 
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INSTALLING AN INTERRUPT HANDLER 


If you plan to use a peripheral card which supports interrupts, 
you may want to write an interrupt handler for that card. You 
should use the ProDOS first level interrupt handler in the Kernel 
so that other cards may also service their interrupts. To do this, use 
the MLI:ALLOCINTERRUPT call to install your interrupt 
handler’s entry address in the interrupt vector table within the 
ProDOS System Global Page. When writing an interrupt handler, 
follow these steps in the order indicated. 


1. Make sure your interrupt handler is stored in main memory 
between $200 and $BEFF. 

2. Call the MLI with the ALLOCINTERRUPT ($40) call to 
cause your routine’s entry point to be placed in the vector table. 

3. Perform whatever I/O is necessary specific to your peripheral 
to enable its interrupt generating mechanism. 


When your interrupt routine is called, the first instruction 
executed should be a CLD (to let ProDOS know that this is a valid 
externally written routine). You should then determine whether 
the interrupt which caused your routine to be invoked was indeed 
from your peripheral. If it was not, return to the Kernel with the 
carry flag set. If it was, service the interrupt, and upon completion, 
return to the Kernel with the carry flag clear. Your interrupt 
handler need not save or restore any registers, and it may use up to 
16 bytes of stack space and zero page locations $FA through $F F 
(these are saved and restored by the Kernel). The Kernel assumes 
that the “bottom” of the stack is at $1F F when it determines what 
to save. Your application should always start the stack pointer at 
$FF. Note that the Motherboard ROM is deactivated in an 
interrupt handler routine (do not attempt to print via $FDED, for 
example). 

If you wish to remove a previously installed interrupt routine, 
first disable the interrupt generation mechanism on your 
peripheral card to prevent further interrupts from occurring, then 
call the MLI:DEALLOCINTERRUPT function to remove your 
handler from the list. 
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When writing an interrupt service routine, you should minimize 
the actual function performed “on the interrupt.” If you are 
collecting data from a serial port which will later be written to 
disk, do not write the data while in the interrupt service routine, 
since this may adversely impact the performance of the program 
which was executing when the interrupt occurred, or it may cause 
you to “lose” subsequent interrupts while processing the first. 
Instead, use the interrupt routine to fill a “circular buffer” which 
is periodically dumped to disk by the interrupted program. An 
example of this technique and of writing interrupt handlers in 
general is given in the DUMBTERM program in APPENDIX A. 

If you. wish to call the MLI while in an interrupt routine, you 
should take steps to allow any interrupted MLI call to complete 
before using the MLI yourself (the MLI is not reentrant). Check 
the MLIACTV flag (SBF 9B) in the System Global Page to see if the 
ML is active. If the MLI is not active, you may issue MLI calls 





ANDUING 
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immediately. If the MLI is active, save the contents of CMDADR 
($BF9C) and replace it with an address within your service 
routine. Then return to the Kernel with the carry clear. When the 
MLI call completes, control will be passed to you instead of the 
original MLI caller. You should carefully save all registers, 
perform your processing: as needed, restore the registers again, 
and jump to the saved contents of CMDADR to allow the original 
caller to continue. Note that you can be interrupted during your 
processing unless you disable interrupts. If you are not careful, a 
subsequent interrupt could cause your interrupt service routine to 
overwrite the saved contents of CMDADR with an address within 
your own program, causing an infinite loop! It might be a good 
idea to set a flag when saving CMDADR and clear it only when you 
have completed all processing. Your interrupt service routine can 
then check the flag and discard any interrupts which occur while 
you are finishing up processing of the first interrupt. 


y 


Lf , eae a 
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DIRECT MODIFICATION OF ProbOS—A WORD OF 
WARNING 


Making changes to your copy of ProDOS should only be 
undertaken when absolutely necessary. In the past, many third 
party software packages were sold for DOS, the earlier Apple II 
operating system, which patched or made wholesale changes. 
Because of the dependency these programs had on fixed locations 
within DOS and their importance to the collective software 
offering for the machine, programmers at Apple felt hampered in 
their efforts to improve DOS. Bugs in DOS could only be fixed 
with patches to existing code—no reassembly could be performed 
on the DOS code as this would cause critical locations to move “out 
from under” existing applications. With the introduction of 
ProDOS, Apple started out fresh. Earlier shortcomings in DOS 
have been corrected with ProDOS and numerous enhancements 
have been added. Hopefully, most packages written for ProDOS 
will not have to depend on changing the operating system’s code 
itself. In any case, be forewarned: Apple will not hesitate to 
reassemble the ProDOS Kernel or the BASIC Interpreter or other 
ProDOS components if changes are desirable, and the stated policy 
is that programs which depend on locations or entry points which 
are not published by Apple will do so at their own risk. 


OVE>CUSTOMIZE Probosy 
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Although ProDOS provides most of the functionality needed by 
the BASIC or assembly language programmer, at times a custom 
change is desirable. When making a change, weigh its value 
against the difficulty of reconstructing and reapplying it for later 
versions of ProDOS as they become available. Of course, if you 
never plan to upgrade your version of ProDOS this is not a 
concern. In addition, wholesale modification of ProDOS without a 
clear understanding of the full implications of each change can 
result in an unreliable system. 


APPLYING PATCHES TO ProDOS 

The usual procedure for making changes to ProDOS involves 
“patching” the object or machine language code in ProDOS. Once a 
desired change is identified, a few instructions are stored over 
other instructions within ProDOS to modify the program. There 
are three levels at which changes to ProDOS may be applied. 


@ New code may be written and added to ProDOS through a 
“standard” interface. If this is done, as in the case of an 
interrupt handler, for example, there need not be any ProDOS 
version dependencies involved. Examples of this type of 
modification have been given earlier in this chapter. 

@ A patch may be applied toa ProDOS system component, such as 
the Kernel or the BASIC Interpreter, directly in memory. If this 
is done, a later reboot will cause the change to “fall out” or be 
removed. This method is usually used to test a change before 
making it permanent. 

@ A patch may be made directly to the diskette containing the 
ProDOS system component in question. Most ProDOS 
components are stored as SYS files and may be BLOADed, 
modified using the monitor, and BSAVEd back to diskette. Ifa 
change is to be made to the bootstrap loader (stored in block 0 of 
the volume), a sector editor or the ZAP program given in 
APPENDIX A must be used. When applying patches to the 
BASIC.SYSTEM or PRODOS files, you can find a location 
within the unrelocated image of the BI or the Kernel if you know 
its address in the relocated and running version. To do this, refer 
to Table 7.1. For example, if you wish to patch $9B7C in the BI, 
you must patch $257C after BLOADing BASIC.SYSTEM. If 
you wish to change $D32A in the MLI, BLOAD PRODOS and 
change $302A. 


7-20 Beneath Apple ProDOS 





Table 74a ProDOS Patch Locations For FILE = “PRODOS” (64K) 


EXECUTION IMAGE 
ADDRESS ADDRESS 




























































































































BFO0O 4E00 (64K sytem global page image) 
D000 2D00 (alternate 4K: 5900—QUIT code) 
D100 2E00 (alternate 4K: 5A00) 
D200 2F00 (alternate 4K: 5B00) 
D300 3000 

D400 3100 

D500 3200 

D600 3300 

D700 3400 

D800 3500 

D900 3600 

DA00 3700 

DBOO 3800 

DC00 3900 

DD00 3A00 

DE00 3B00 

DF00 3C00 

E000 3D00 

E100 3E00 

E200 38F00 

E300 4000 

E400 4100 

E500 4200 

E600 4300 

E700 4400 

E800 4500 

E900 4600 

EA00 4700 

EBOO 4800 

EC00 4900 

EDOO 4A00 

EEOO 4B00 

EFOO 4C00 

F000 4D00 

F100 zeroed (clock code to F142 from 5000) 
F200 zeroed 

F300 zeroed 

F400 zeroed 

F500 zeroed 

F600 zeroed 

F700 zeroed 

F800 5200 (diskette driver) 
F900 5800 

FAOO 5400 

FBOO 5500 

FCO0O 5600 

F DOO 5700 

FEOO 5800 

FFOO 2C00 (/RAM device driver through FF8C) 


FF80 5080 (Interrupt vectors and handler, 


starts at FF9B) 
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Table 7.1b ProDOS Patch Locations For FILE = “BASIC.SYSTEM” 


EXECUTION IMAGE 
ADDRESS ADDRESS 


2400 (Blimage) 
500 






mage) 





4700 (BI Global Page i 





The patches given here are applied directly to a diskette with 
ProDOS Version 1.0.1 (1 January 1984). You must reboot after 
making any changes in order to cause them to take effect. Do not 
make these changes to your original ProDOS System diskette. 
Modify a copy so you can “back out” any changes you make by 
copying the original again. 
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CHANGING THE NAME OF THE STARTUP FILE 


You can change the name of the STARTUP file which the BI 
executes at bootup by patching the first block of BASIC.SYSTEM 
as follows. 


BLOAD BASIC.SYSTEM,TSYS,AS2086 
CALL -151l 

21E5:@5 48 45 4C 4C 4F 

BSAVE BASIC.SYSTEM,TSYS ,AS200G 


Here we are changing the name from STARTUP to HELLO. 
The first byte indicates the number of characters in the name (5) 
and may be a maximum of 7 characters. Each ASCII byte should 
have its most significant bit off. The Startup file may be of any 
type which can be run using the “—” (Smart RUN) command. 


PUT CURSOR ON COMMAND THAT CAUSED ProDOS ERROR 

When you get a ProDOS error message such as “PATH NOT 
FOUND” or “FILE TYPE MISMATCH” because you typed the 
wrong file name or misspelled it slightly, it would be nice if 
ProDOS would return the cursor on the line with your faulty 
command so you could easily retype it. Toe make ProDOS do this 
from now on, apply the following patches. 


BLOAD BASIC.SYSTEM,TSYS ,AS2686 

CALL -151 

257C:4C Cd BB 

45C@:A4 25 88 88 88 84 25 206 22 FC 4C 3F D4 
BSAVE BASIC.SYSTEM,TSYS,AS296@ 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will not work with other versions. 
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HOW TO WRITE TO A DIRECTORY FILE 

The ProDOS MLI will not allow explicit WRITEs to a directory 
file under any circumstances (it makes no difference whether the 
DIR file is “locked” or not). Under normal conditions, the only 
program which may modify a directory file is the MLI itself (when 
CREATEing a new file, updating the INFO in an old one, or 
DESTROYing one). If you wish to directly modify a directory 
entry with your own program, you should follow this procedure to 


circumvent the MLI. 


1. Open the directory file using MLI-OPEN. 
2. READ the block requiring update. 
3. Execute the following code to find the block number. 


LDA 
LDA 
LDA 
CLC 
SBC 
LSR 
ROR 
ROR 
ROR 
TAX 
LDA 
STA 
LDA 
STA 
STA 


SCO8B 
SCO8B 
REFNUM 


#9 
A 
A 
A 
A 


SF310,X 
BLKNUM 
$F311,X 
BLKNUM+1 
$C@81 


SELECT RAM CARD 
PICK UP REF NUM OF FILE 


MAKE IT AN OFFSET 
*32 FOR INDEX INTO FCB'S 


GET CURRENT BLOCK NO. 


SELECT MOTHERBOARD ROMS 


4. Use MLI:WRITE_BLOCK to write back the block. 
Note that $F310 and $F311 may be version dependent locations. 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will not work with other versions. 
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CREATING A NEW FILE TYPE 

When you CREATE a file with the MLI, you may specify any file 
type you wish. If you wish to define a new file type for your 
application, pick a number between $F 1 and $F8. When a CAT or 
CATALOG command is issued in the BASIC Interpreter, the file 
type listed will be “$F n”. If you want to use a three letter 
abbreviation instead, you must modify the table in the BI. The 
patch given below is highly version dependent and will only work 
for ProDOS Version 1.0.1 (1 January 1984). 

The first thing to do is examine the table of file types in the BI at 
$B9DB. This table consists of 14 entries of one byte each, giving 
the ProDOS file type number for each of the supported types. You 
will have to replace one of the entries that you never use with your 
own file type. The entries need not be in numerical order. 
Immediately following the type table is a table of 3-byte entries 
giving the names which correspond to the numeric types. This 
table is in reverse order to the first and begins at $B9E9. As an 
example, suppose you wished to replace the last entry in the tables, 
$19 “ADB”, with $F 1 “ABC”. 


BLOAD BASIC.SYSTEM,TSYS ,AS2008 
CALL -151 

43E8:F1 

43E9:Cl C2 C3 

BSAVE BASIC.SYSTEM,TSYS ,AS20600 


Notice that $B9E8 maps to $43E8 in the unrelocated image of 
BASIC.SYSTEM. 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will not work with other versions. 
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RECOVERING DATA FROM A DAMAGED DISK 


If one of the sectors which makes up a block is damaged, 
ProDOS will return with an I/O error. If in fact the error was in 
the second half of the block, the first half will be read into memory 
before the I/O error occurs. However, if the error is in the first half 
of the block, ProDOS will not attempt to read the second half. To 
recover the second, undamaged sector of the block, the following 
patch will force ProDOS to ignore any errors while reading the 
first half of a block. Errors while reading the second half will still 
behave normally. 


BLOAD PRODOS, TSYS, AS$2986 
CALL -151 

5228:08 

BSAVE PRODOS, TSYS, AS20606 


The above patch, while it will work properly with undamaged 
blocks, is not advisable in normal use as it will fail to indicate when 
errors have occurred. 


USING ProDOS WITH 40-TRACK DRIVES 

The device driver supplied with ProDOS supports only 35 
tracks. The code can be modified easily to support third party disk 
drives with 40 tracks, but there are a couple of things to consider. 
The patch will apply to all drives (regardless of the number of 
tracks supported) connected to Disk II or compatible controller 
cards. This should cause no difficulties even if one 35-track and one 
40-track drive are on the same controller card. Because you will 
also want to format 40-track disks, it will be necessary to modify 
FILER. The patch to FILER will apply to all disks that you 
format, and will produce an error if you attempt to format a disk 
on a drive supporting less than 40 tracks. 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will! not work with other versions. 
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This patch modifies the ProDOS Version 1.0.1 Disk IT Device 
Driver to allow 320 blocks instead of the norma! 280. 


UNLOCK PRODOS 
BLOAD PRODOS, TSYS,AS$2900 


CALL -151 
520D:4@ 
3D6G 


BSAVE PRODOS, TSYS,A$2009 
LOCK PRODOS 


This patch modifies FILER* to format 40 tracks instead of 35. It 
will not work on a 35-track drive. 


UNLOCK FILER 

BLOAD FILER, TSYS,A$2009 
CALL -151 

4244:49 

79F4:28 

3D08G 

BSAVE FILER, TSYS,AS$290¢ 
LOCK FILER 


*Unlike the patch to ProDOS, this patch need not be applied to the disk. You may 
wish simply to make the patch and execute the program. To do this, replace 3D0G 
with 2000G, and don’t BSAVE FILER. This patch works on the version of FILER 
released in 1984. It does not work with some pre-release versions, and may not 
work with future releases of FILER. 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will not work with other versions. 
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FORCING ProDOS TO LOAD IN 48K 

It is possible to load the ProDOS Kernel in main RAM (rather 
than in the bank switched memory or Language Card). In this 
case, you cannot use the BASIC Interpreter (since it is assembled 
for a fixed location which conflicts with the alternate location of 
the Kernel), or EDASM.SYSTEM from the toolkit package. You 
can, however, use other programs, such as the EXERCISER or 
BUGBYTER. Forcing a 48K load is sometimes useful even in a 
larger machine if you want to trace execution into the ProDOS 
Kernel itself using BUGBYTER. Under ordinary circumstances, 
as soon as the bank switched memory is enabled, the ROM monitor 
disappears and BUGBYTER goes berserk! If the Kernel is in main 
RAM, however, this does not occur. To force a 48K load you must 
first place a “SYSTEM” program (with type SYS) on the diskette 
to be booted (make a copy of BUGBYTER called 
BUGBYTER.SYSTEM). This must be the first file whose name 
ends with “SYSTEM” in the Volume Directory. You can then 
apply the following patch and reboot. 


BLOAD BUGBYTER 

CREATE BUGBYTER.SYSTEM,TSYS 

BSAVE BUGBYTER.SYSTEM,TSYS ,A$2609,L7177 
BLOAD PRODOS,TSYS,A$2666 

CALL -151 

23FC:A9 5@ 

BSAVE PRODOS,TSYS ,A$2006 


Note that the value of $50 above is the MACHID desired (Apple 
II Plus with 48K). You may add to that the bits necessary for an 
80-column card or Thunderclock if you like. You may wish to 
append your own program to the BUGBYTER.SYSTEM image 
before BSAVEing it so that it will be available to you once the 48K 
system is loaded. You can do this by inserting a BLOAD 
MYPGM,A$3D00 after the CREATE, and changing the length of 
the BSAVE to accomodate BUGBYTER and your program 
combined. When you boot the 48K diskette, your program will be 
loaded at $3D00, immediately following BUGBYTER. 


NOTE: The patches described on this page are for Version 1.0.1 of ProDOS and 
probably will not work with other versions. 





CHAPTER 8 


ProDOS GLOBAL PAGES 


Readers of Beneath Apple DOS may remember that Chapter 8 of 
that book was devoted to a detailed analysis of DOS program logic. 
The contents of that chapter comprised one quarter of the book, 
and represented a complete description of more than 10K of 
machine language code. Two factors have led to the approach 
taken in Beneath Apple ProDOS. First, ProDOS code is expected 
to be much more volatile than that of DOS. If material similar to 
Chapter 8 in Beneath Apple DOS had been published here, it would 
have quickly become obsolete because of reassemblies of the oper- 
ating system components by Apple. Throughout its lifetime, DOS 
was only completely reassembled once—when the change was 
made from 3.1 to 3.2 in 1979. Our book documented a form of DOS 
in which most of the instructions had not “moved” in nearly five 
years! In contrast, before Beneath Apple ProDOS was published, 
two different versions of ProDOS were already being distrib- 
uted—1.0.1 and 1.0.2. Although the differences between them are 
very minor, insertions of instructions and data have caused the 
shifting of major sections of code. Similar changes are expected in 
the future. 

A second factor in the decision to shorten Chapter 8 involved the 
physical size of ProDOS. The equivalent components of ProDOS, 
compared to the DOS code covered in our earlier book, occupy over 
22K of memory. A complete treatment of this code would be a book 
in and of itself. Coupled with the increased complexity of ProDOS 
which has resulted in longer chapters overall, as well as the pre- 
viously mentioned volatility of the code, we decided that an in- 
depth coverage of ProDOS program logic did not belong here. 
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However, recognizing the importance of this material to many 
of our readers, a special supplement has been prepared that 
provides a detailed description of every piece of code and data 
within the major ProDOS components. It is available directly 
from Quality Software. Updated editions of this supplement will 
be available on a periodic basis as Apple releases new versions of 
ProDOS. In addition, any errata and changes to the main body of 
Beneath Apple ProDOS will be found in future supplements, 
eliminating the need to buy future editions of this book. 
Instructions for ordering the supplement are provided at the 
end of this chapter. 


BASIC INTERPRETER GLOBAL PAGE 


This page of memory is rigidly defined by the ProDOS BI. 
Fields given here will not move in later versions of ProDOS and 
may be referenced by external, user-written programs. Future 
additions to the global page may be made in areas which are 
marked “Not used”. 


ADDRESS LABEL CONTENTS 
BE00-BE02 BIENTRY JMP to WARMDOS (BI warmstart 
vector). 


BE03-BE05 DOSCMD JMP to SYNTAX (BI command line 
parse and execute). 

BE06-BE08 EXTRNCMD JMPtouser-installed external 
command parser. 

BE09-BE0OB ERROUT JMP to Bl error handler. 

BEOC-BEOE PRINTERR JMP to BI error message print 
routine. Place error number in 


A-register. 

BEOF ERRCODE ProDOS error code (also at $DE, 
Applesoft ONERR code). 

BE10-BE1F OUTVEC Default output vector in monitor and 
for each slot (1-7). 

BE20-BE2F INVEC Default input vector in monitor for 


each slot (1-7). 
BE30-BE31 VECTOUT Current output vector. 
BE32-BE33 VECTIN Current input vector. 
BE34-BE35 VDOSIO BI’s output intercept address. 


BE36-BE37 


BE38-BE3B VSYSIO 
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BI’s input intercept address. 
BI’s internal redirection by STATE. 


BE3C DEFSLT Default slot. 
BE3D DEFDRV Default drive. 
BE3E PREGA A-register savearea. 
BE3F PREGX X-register savearea. 
BE40 PREGY Y-register savearea. 
BE41 DTRACE Applesoft TRACE is enabled flag 
(MSB on). 
BE42 STATE Current intercept state. 0 = 
immediate command mode. >0= 
deferred. 
BE43 EXACTV EXEC file active flag (MSB on). 
BE44 IFILACTV READ file active flag (MSB on). 
BE45 OFILACTV WRITE file active flag (MSB on). 
BE46 PFXACTV PREFIX read active flag (MSB on). 
BE47 DIRFLG File being READ is a DIR file (MSB on). 
BE48 EDIRFLG End of directory flag (no longer used). 
BE49 STRINGS String space count used to determine 
when to garbage collect. 
BE4A TBUFPTR Buffered WRITE data length. 
BE4B INPTR Command line assembly length. 
BE4C CHRLAST Previous output character (for 
recursion check). 
BE4D OPENCNT Number of files open (not counting 
EXEC). 
BE4E EXFILE EXEC file being closed flag (MSB on). 
BE4F CATFLAG Line type to format next in DIR file 
READ. 
BE50-BE51 XTRNADDR External command handler address. 
BE52 XLEN Length of command name (less one). 
BE53 XCNUM Number of command: 
$00 =external $0A =OPEN $14  =WRITE 
$01 =IN# $0B =READ $15 =APPEND 
$02 =PR# $0C =SAVE $16 =CREATE 
$03 =CAT $0D =BLOAD $17 =DELETE 
$04 =FRE $0E =BSAVE $18 =PREFIX 
$05 =RUN $0F =CHAIN $19 =RENAME 
$06 =BRUN $10 =CLOSE $1A =UNLOCK 
$07 =EXEC $11 =FLUSH $1B =VERIFY 
$08 =LOAD $12 =NOMON $1C =CATALOG 
$09 =SAVE $13 =STORE $1D =RESTORE 
$1E =POSITION 
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BE54-BE55 


BE56-BE57 


BE58-BE59 
BES5A-BE5C 
BE5D-BE5E 
BE5F-BE60 
BE61 

BE62 
BE63-BE64 
BE65-BE66 
BE67 
BE68-BE69 
BE6A 

BE6B 
BE6C-BE6D 


BE6E-BE6F 
BE70-BE84 


BE85 
BE86-BE87 


BE88-BE8A 
BE8B-BE9E 


BE9SF 
BEA0-BEAB 
BEAC-BEAE 


PBITS 


‘$8000 
$4000 
$2000 
$1000 
$0800 
$0400 
$0200 
$0100 
$0080 
$0040 
$0020 
$0010 
$0008 
$0004 
$0002 
$0001 


FBITS 


VADDR 
VBYTE 
VENDA 
VLNTH 
VSLOT 
VDRIV 
VFELD 
VRECD 
VVOLM 
VLINE 
VTYPE 
VIOSLT 
VPATHI1 


VPATH2 
GOSYSTEM 
SYSCALL 
SYSPARM 
BADCALL 
BISPARE1 


SCREATE 
SSGPRFX 


Permitted command operands bits: 


Prefix needed. Pathname optional. 
Slot number only (PR# or IN#). 
Deferred command. 

File name optional. 

If file does not exist, create it. 

T: file type permitted. 

Second file name required. 

First file name required. 

AD: address keyword permitted. 
B: byte offset permitted. 

E: ending address permitted. 

L: length permitted. 

‘@: line number permitted. 

Sor D: slot/drive permitted. 

F: field permitted. 

R: record permitted. 

(V always permitted but ignored.) 


Operands found on command line. 
Same bit assignments as above. 

A keyword value. 

B keyword value. 

E keyword value. 

L keyword value. 

S keyword value. 

D keyword value. 

F keyword value. 

R keyword value. 

V keyword value (ignored). 

@ keyword value. 

T keyword value (in hex). 

PR# or IN# slot number value. 
Primary pathname buffer (address 
of length byte). 

Secondary pathname buffer 
(address of length byte). 

Call the MLI using the parameter 
tables which follow. 

MLI call number for this call. 
Address of MLI parameter list for 
this call. 

Return from MLI call. 

MLI error return: translate error 
code to BI error number. 

Not used. 

CREATE parameter list. 
GET_PREFIX, SET_PREFIX, 
DESTROY parameter list. 


BEAF-BEB3 
BEB4-BEC5 


BEC6-BECA 


BECB-BEDO 
BED1-BED4 
BED5-BEDC 


BEDD-BEDE 


BEDF-BEF4 
BEF5-BEF7 


BEF8-BEFA 
BEFB 


BEFC-BEFF 
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SRENAME RENAME parameter list. 

SSGINFO GET_FILE_INFO, 
SET_FILE_INFO parameter list. 

SONLINE ONLINE, SET_MARK, 
GET_MARK, SET_EOF, 
GET_EOF, SET_BUF, GET_BUF, 
QUIT parameter list. 

SOPEN OPEN parameter list. 

SNEWLN SET_NEWLINE parameter list. 

SREAD READ, WRITE parameter list. 

SCLOSE CLOSE, FLUSH parameter list. 

CCCSPARE “COPYRIGHT APPLE, 1983” 

GETBUFR GETBUER buffer allocation 
subroutine vector. 

FREEBUFR FREEBUFR buffer free subroutine 


vector. 
Original HIMEM MSB. 
Not used. 


ProDOS SYSTEM GLOBAL PAGE—MLI Giobal Page 


Portions of this page of memory are rigidly defined by the MLI 
and are unlikely to move in later versions of ProDOS. However, 
some portions are less stable and could change in future releases. 


ADDRESS LABEL CONTENTS 
Jump Vectors 
BF00-BF02 ENTRY JMP to MLI. 
BF03-BF05 JSPARE Jump to system death code (via 
$BFF6). 
BF06-BF08 DATETIME Jump to Date/Time routine (RTS if no 
clock). 
BF09-BFOB ‘SYSERR JMP to system error handler. 
BFOC-BFOE SYSDEATH JMP tosystem death handler. 
BFOF SERR System error number. 
na SON HAS BEEN 
USING A COMPUTER SINCE 
HE WAS 3 YEARS OLD. 





7 E HE‘ A 
Te RE Tpit 
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BF10-BF11 
BF12-BF13 
BF14-BF15 
BF16-BF17 
BF18-BF19 
BF1A-BFIB 
BF1C-BF1D 
BFIE-BFIF 
BF20-BF21 
BF22-BF23 
BF24-BF25 
BF26-BF27 


BF28-BF29 
BF2A-BF2B 
BF2C-BF2D 
BF2E-BF2F 
BF30 


BF31 
BF32-BF3F 


BF40-BF4F 
BF50-BF55 


BF56-BF57 
BF58-BF6F 
BF70-BF71 
BF72-BF73 
BF74-BF75 
BF76-BF77 
BF78-BF79 
BF7A-BF7B 
BF7C-BF7D 
BF7E-BF7F 


BF80-BF81 


BF82-BF83 
BF84-BF85 
BF86-BF87 


BF88 
BF89 
BF8A 


Device Information 


DEVADRO1 
DEVADRI1 
DEVADR21 
DEVADR31 
DEVADR41 
DEVADR51 
DEVADR61 
DEVADR71 
DEVADR02 
DEVADRI2 
DEVADR22 
DEVADR32 


DEVADR42 
DEVADR52 
DEVADR62 
DEVADR72 
DEVNUM 


DEVCNT 
DEVLST 


IRQXITX 


TEMP 
BITMAP 
BUFFERI 
BUFFER2 
BUFFER3 
BUFFER4 
BUFFERS 
BUFFER6 
BUFFER7 
BUFFER8 


Slot 0 reserved. 

Slot 1, drive 1 device driver address. 
Slot 2, drive 1 device driver address. 
Slot 3, drive 1 device driver address. 
Slot 4, drive 1 device driver address. 
Slot 5, drive 1 device driver address. 
Slot 6, drive 1 device driver address. 
Slot 7, drive 1 device driver address. 
Slot 0 reserved. 

Slot 1, drive 2 device driver address. 
Slot 2, drive 2 device driver address. 


/RAM device driver address (need extra 


64K). 

Slot 4, drive 2 device driver address. 
Slot 5, drive 2 device driver address. 
Slot 6, drive 2 device driver address. 
Slot 7, drive 2 device driver address. 
Slot and drive (DSSS0000) of last 
device. 

Count (minus 1) of active devices. 
List of active devices (slot, drive and 
identification—DSSSITID). 
Copyright notice. 

Switch in language card and cal] IRQ 
handler at $F FD8. 

Temporary storage for IRQ code. 
Bitmap of low 48K of memory. 
Open file 1 buffer address. 

Open file 2 buffer address. 

Open file 3 buffer address. 

Open file 4 buffer address. 

Open file 5 buffer address. 

Open file 6 buffer address. 

Open file 7 buffer address. 

Open file 8 buffer address. 


Interrupt Information 


INTRUPTI1 


INTRUPT2 
INTRUPT3 
INTRUPT4 


INTAREG 
INTXREG 
INTYREG 


Interrupt handler address (highest 
priority). 

Interrupt handler address. 
Interrupt handler address. 
Interrupt handler address (lowest 
priority). 

A-register savearea. 

X-register savearea. 

Y-register savearea. 
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BF8B INTSREG S-register savearea. 

BF8C INTPREG P-register savearea. 

BF8D INTBANKID Bank ID byte (ROM, RAMI, or 
RAM2). 


BF8E-BF8F INTADDR Interrupt return address. 


General System Info 


BF90-BF91 DATE YYYYYYYM MMMDDDDD. 
BF92-BF93. TIME ..HHHHH .MMMMMM. 
BF94 LEVEL Current file level. 
BF95 BUBIT Backup bit. 
BF96-BF97 SPARE] Currently unused. 
BF98 MACHID Machine ID byte. 
00.. 0... II 
Ol. 0... I+ 
10.0... Ile 
11. 0... IIT emulation 
00. 1... Future expansion 
Ol. od. Future expansion 
10.. 1... IIc 
11. 1... Future expansion 
..00 des Unused 
01 Sth 48K 
10 aes 64K 
mel See 128K 
: X.. Reserved 
0. No 80-column card 
sols 80-column card present 
0 No compatible clock 
ma Compatible clock present 
BF99 SLTBYT Slot ROM map (bit on indicates ROM 
present). 
BF9A PFIXPTR Prefix flag (0 indicates no active prefix). 
BF9B MLIACTV MLi active flag (1... .... indicates 
active). 
BF9C-BF9D CMDADR Last MLI call return address. 
BF9E SAVEX X-register savearea for MLI calls. 
BF9OF SAVEY Y-register savearea for MLI calls. 


Language Card Bank Switching Routines 


BFA0-BFCF Language card entry and exit routines. 
BFAO EXIT 
BFAA EXIT1 
BFB5 EXIT2 
BFB7 MLIENT1 
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Interrupt Routines 

BFDO-BFF3 Interrupt entry and exit routines. 

BFDO IRQXIT 

BFDF IRQXIT1 

BFE2 IRQXIT2 

BFE7 ROMXIT 

BFEB IRQENT 

Data 

BFF4 BNKBYT1 = Storage for byte at $E000. 
BFFS5 BNKBYT2 = Storage for byte at $D000. 
BFF6-BFFB Switch on language card and call 


system death handler ($D1E4). 


Version Information 


BFFC IBAKVER Minimum version of Kernel needed 
for this interpreter. 

BFFD IVERSION _ Version number of this interpreter. 

BFFE KBAKVER Minimum version of Kernel 
compatible with this Kernel. 

BFFF KVERSION _ Version number of this Kernel. 


ORDERING THE SUPPLEMENT TO BENEATH APPLE ProDOS 


Each owner of Beneath Apple ProDOS may order the latest 
updated supplement. The supplement describes in detail every 
piece of code and data within the major ProDOS components (see 
page 8-2). To order the supplement, you must mail the coupon on 
the next page directly to Quality Software (at the address on the 
coupon), along with a payment of $10.00 plus shipping and 
handling charges.* Your payment can be a check or bank draft in 
US dollars, or your VISA or MasterCard number and expiration 
date. California residents must add the appropriate sales tax (6 or 
6.5%). No phone orders or CODs will be accepted. 


*SHIPPING & HANDLING CHARGES 
United States. Canada, and Mexico ......... $ 2.50 
All other countries (insured air mail) ....... $10.00 
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Qs QUALITY SOFTWARE 


21601 Marilla Street 
Chatsworth, CA 91311 
(818) 709-1721 


SUPPLEMENT COUPON 


Please cut this page out of the book and mail it (not a copy) to 
Quality Software. Each supplement contains a coupon for ordering 
a subsequent supplement. 


Please send me: 

____ The latest updated supplement, OR 

____. The supplement that matches my version of ProDOS, 
VERSION 


Name 
Street Address 
City, State, Postal Code 








Country 





Supplement $10.00 
(CA residents) Sales Tax 
Shipping & Handling 


TOTAL 


Check # 
OR VISA/Mastercard # Expires 








Price subjeet to change without notice (3/85) 
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Valid Coupon 


APPENDIX A 


EXAMPLE PROGRAMS 


This section is intended to supply the reader with utility 
programs which can be used to examine and repair diskettes, as 
well as typical programming applications for ProDOS. These 
programs are provided in their source form to serve as examples of 
the programming necessary to interface practical programs to 
ProDOS. The reader who does not know assembly language may 
also benefit from these programs by entering them from the 
monitor in their binary form and saving them to disk for later use. 
The use of diskettes is assumed, although most of the programs 
will work with a hard disk or can be easily modified for this 
purpose. It is reeommended that, until the reader is completely 
familiar with the operation of these programs, he should use them 
on an “expendable” diskette. None of the programs can physically 
damage a diskette, but they can, if used improperly, destroy the 
data on a diskette, requiring it to be reinitialized. 

Seven programs are provided: 


DUMP TRACK DUMP UTILITY 
This is an example of how to access the disk drive 
directly through its I/O select addresses. DUMP may 
be used to dump to memory any given track in its 
raw, prenibblized form. This can be useful both in 
understanding how disks are formatted, and in 
diagnosing clobbered diskettes. DUMP will only 
operate on a Disk II drive or its equivalent. 
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FORMAT REFORMAT A RANGE OF TRACKS 
This program will initialize a single track or a range 
of tracks on a diskette. FORMAT is useful in 
restoring a track whose sectoring has been damaged 
without reinitializing the entire diskette. FORMAT 
will only operate on a Disk II drive or its equivalent. 


ZAP DISK UPDATE UTILITY 
This program is the backbone of any attempt to patch 
a disk directory back together. It is also useful in 
examining the structure of files stored on disk and in 
applying patches to files or ProDOS directly. ZAP 
allows its user to read, and optionally write, any block 
on a disk volume. As such, it serves as a good example 
of a program which issues direct block I/O calls to the 
MLI. 


MAP MAP FREESPACE ON A VOLUME 
MAP is written in BASIC and proves that direct 
block I/O can be done directly from a BASIC 
program as well as from assembly language. MAP 
reads the volume freespace bit map and displays a 
map of freespace versus blocks in use on the screen. 


FIB FIND INDEX BLOCKS UTILITY 
FIB may be used when a directory for a volume has 
been destroyed. It searches every block on a volume 
for what appear to be index blocks, printing the block 
number location of each index block it finds: Knowing 
the locations of the index blocks and employing ZAP, 
the user can patch together a new directory. 


TYPE TYPE COMMAND 
The TYPE command may be added to the ProDOS BI 
as anew command. It allows a user to type (display) 
the contents of a file to the screen or a printer. TYPE 
serves as an example of an external command 
handler. 


DUMBTERM DUMBTERMINAL PROGRAM 
DUMBTERM serves as an example of programming 
with interrupts. It implements a simple terminal 
emulator program, using a CCS 7710 serial interface 
card. Interrupts are used to fill a circular buffer, 
allowing higher baud rates to be used. 
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STORING THE PROGRAMS ON DISKETTE 


The enterprising programmer may wish to key in the source 
code for each program into an assembler and assemble the 
programs onto disk. The Apple ProDOS Assembler was used to 
produce the listings presented here, and interested programmers 
should consult the documentation for that assembler for more 
information on the pseudo-opcodes used. For the non-assembly 
language programmer, the binary object code of each program 
may be entered from the monitor using the following procedure. 

The assembly language listings consist of columns of 
information as follows. 


e The address of some object code 

e The object code which should be stored there 
e The statement number 

e The statement itself 


For example, 
208G:A9 62 36 FIB LDA #2 BLOCK = 2 


indicates that the binary code “A902” should be stored at $2000 
and that this is statement 36. To enter a program in the monitor, 
the reader must type in each address and its corresponding object 
code. The following is an example of how to enter the FIB 
program. 


CALL -151 (enter the monitor) 
2000:A9 @2 

2002:8D EY 2¢ 

2005:A9 @@ 

2007:8D EA 2¢ 


ee -etc. ee 
2GEB:66 GG 


2GED:98 8G 
BSAVE FIB,AS29090,LSEF 
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Note that if a line (such-as line 2 in FIB) has no object bytes 
associated with it, it may-be ignored. Also, never type in a four 
‘digit hex number, such as the ones found in FIB on lines 22 
through 27 or the “2044” on line 41—type only two digit object code 
numbers. 

When the program is to be run: 


.BLOAD FIB 
CALL -151 
2866G 


The BSAVE commands which must be used with the other 
programs are: 


BSAVE DUMP ,A$2000,LS100 
-BSAVE FORMAT ,AS28908,L$51C 
BSAVE ZAP,AS2@6@,L$47 
BSAVE FIB,A$2@69,LSEF 
BSAVE DUMBTERM,AS20008,LSF7 
BSAVE TYPE,AS200@6,L$1B4 


A diskette containing these seven programs is available ata 
reasonable cost directly from Quality Software, 21601 Marilla 
Street, Chatsworth, CA 91311 or telephone (818) 709-1721. 


DUMP—TRACK DUMP UTILITY 


The DUMP program will dump any track ona diskette in its 
raw, pre-nibbilized format, allowing the.user to examine the sector 
address and data fields and the formatting of the track. This 
allows the inquisitive reader to examine his own diskettes to better 
understand the concepts presented in the preceeding chapters. 
DUMP may also be used to examine some protected disks to see 
how they differ from normal ones and to diagnose diskettes with 
clobbered-sector address or data fields with the intention of 
recovering from disk I/O errors. The DUMP program serves as an 
example of direct use of the Disk II hardware from assembly 
language, with no use of ProDOS. 
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To use DUMP, first store the number of the track you wish 
dumped at location $2003, the device number you wish to use at 
location $2004 (the program defaults to slot 6, drive 1), and begin 
execution at $2000. DUMP will return to the monitor after 
displaying the first part of the track in hexadecimal on the screen. 
The entire track image is stored, starting at $4000. For example: 


BLOAD DUMP (Load the DUMP program) 
CALL -151 (Get into the monitor from BASIC) 


(Now insert the diskette to be DUMPed) 


2003:11 N 28680G (Store an 11 (track 17) in $2603, 
N terminates the store command, 
go to location $2888) 


The output might look like this... 


400@- DS AA 96 AA AB AA BB AB (Start of sector address) 
4008- AA AB BA DE AA E8 C@ FF 
461¢G- 9E FF FF FF FF FF D5 AA {Start of sector data) 
4@18- AD AE B2 9D AC AE 396 96 {Sector data) 

ere Bt Cees 


Quite often, a sector with an I/O error has only one bit which is in 
error, either in the address or data fields. A particularly patient 
programmer in some circumstances can determine the location of 
the error and devise a means to correct it. 


A CARRY BIT! 
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G009: 1 
cocee NEXT OBJECT FILE 
2000: 2968 2 
2006: 4 
2008: 5 
2009 6 
26090; 7 
2000: 8 
2000: 9 
2000: 10 
2006: ll 
2000: i2 
20008: 13 
2000: 14 
2000: 15 
2080: 16 
2000: 17 
2608; 16 
2000: 28 
2000: BO00 22 
2000: 8O3C 23 
2060; SO3E 24 
2000: 26 
2600: 4068 28 
206986: FCA8 29 
2000: FOB3 38 
2006: 32 
2990: CG8E 34 
2u0e@: cash 35 
2000: C082 36 
2000: C884 37 
2060: CO86 38 
2008: CE88 393 
2000: C89 4@ 
2060: CUBA 4l 
2008: Cesc 42 
2809: CO8E 43 
2HAU: 45 
20GU:4C BA 26 47 
2403:86 49 
2604:6¢6 BY’) 
2065:6¢6 51 
2906300 52 
2667:090 $3 
29U8:00 54 
2089:60 55 
260A:AD 64 20 s7 
2000: 48 58 
200E:29 76 $9 
2616:8b 05 29 bu 
2G13:AA 61 
261 62 
261 2018 63 
261 64 
2618 65 
261B:AE 66 
201E:BD 89 CG 67 
2021:BD 8E C@ 68 


* DUMP -- TRACK DUMP UTILITY. 
NAME 1S DUMP.S.@ 
ORG $2000 


A TT TR REE RR EE EERE ERK 


DUMP:THIS PROGRAM WILL ALLOW USER TO DUMP AN ENTIRE 
TRACK IN ITS RAW FORM INTO MEMORY FOR EXAMINATION. 


INPUT: $2003 
$2804 


TRACK TO BE REAO (DEFAULTS TO $98) 
UNIT NUMBER (DEFAULTS TO $60) 


OUTPUT: $4666 


ENTRY POINT: $2000 


PROGRAMMER: PIETER M LECHNER 5/29/84 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 


* 
*« 
* 
* 
* 
* 
* 
ADDRESS OF TRACK IMAGE * 
* 
* 
* 
* 
* 
* 


FORT ORT I OR SOIT IOI TIT tok te 


* ZPAGE DEFINITIONS 


PTR EQU $@ WORK POINTER 
AlL EQU $3c MONITOR POINTER 
A2L EQU S$3E MONITOR POINTER 


* OTHER ADDRESSES 


BUFFER FQU $4668 TRACK IMAGE AREA 
DELAY EQu SFCA8 MONITOR DELAY ROUTINE 
XAM EQu $PDB3 MONITOR HEX DUMP SUBRTN 


* DISK 1/0 SELECTS 


DRVSMB EU SCU8Y STEP MOTOR POSITIONS 

ORVSM1 Equ $CO8i 

ORVSM2 EQu $CG82 

DRVSM4 EQU $COB4 

ORVSM6 EQU SCUse 

DRVOFF EQU $C@88 TURN DRIVE OFF AFTER 6 REVS 
DRVON EQU $C@89 TURN DRIVE ON 

DRVSL] EQuU SCGBA SELECT DRIVE 1 

DRVRD EQU SCBIC READ DATA LATCH 

DRVRDM EQU SCOBE SET READ MODE 


* RECALTBRATE AND POSITION THE ARM TO THE DESIRED TRACK 


ENTRY JMP START SKIP DATA 
TRACK OFB SOG TRACK TO DUMP 
GNITNUM OFB 566 UNIT NUMBER TO USE 
SLOT OFB $60 SLOT NUMBER TO USE 
DESTRK DFB $6o DESTINATION TRACK 
CURTRK DFB $0o CURRENT TRACK 
DELTA DFB $e NUMBER OF TRACKS TO MOVE 
FLAG OFB or) DIRECTION & ODD/EVEN FLAGS 
START LDA UNITNUM GET UNIT NUMBER 
PHA SAVE FOR LATER 
AND #970 GET SLOT ONLY 
STA SLOT 
TAX PUT SLOT IN X REG 
PLA 
BPL DRIVEL SELECT DRIVE 1 
INX SELECT DRIVE 2 
DRIVEL LDA DRVSL1,X SELECT APPROPRIATE DRIVE 
LDX SLOT GET SLOT 
LDA DRVON ,X TURN DRIVE ON 


LDA ORVRDM,X INSURE READ MODE 
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2024:28 


2027:AD 
202A:8D 
2620:28 


2030: 


2030:A9 
2032:85 
2034:A9 
2036:85 
2038:A0 


203A: 
203A: 


2@3A3AE 
283D:BD 
2048:18 
2042:C9 
2034:DO0 
2646:BD 
2049:1¢ 
204B:C9 
2040:08 
204F:30 
2652:19 
2854:C9 
2056:F0 
2€523:008 


205A: 
205A: 
205A; 


265A:BD 
205D:18 
265F:91 
2061266 
2263:04 
26065:E6 
2067210 
2069 2AE 
286C:BD 


256F: 


2B6F 289 
2071285 
2673:A9 
2075:85 
2677:A9 
2079385 
207B:A9 
2070785 
247F24C 


2082: 


28082:A9 
2684:8D 
2087:A9 
2089:8D 
2U8C: 20 
2G68F:AE 
2692:Bd 
2695:BD 
2898:BO 
209B:BD 
209E:68 


20 
ce 
263b 


2830 
ca 
2646 


2830 
ce 
204F 


204F 
205F 


FD 


JSR 


LDA 
STA 
JSR 


* PREPARE TO 


LDA 
STA 
LDA 
STA 
LDY 


RECALC MOVE ARM TO TRACK @ 
TRACK GET TRACK TO READ 
DESTRK 

ARMOVE GO THERE 


DUMP TRACK TO MEMORY 


#>BUFFER POINT AT DATA 
PTR 

#<BUFFER 

PTR+1 

#6 


* START DUMPING AT THE BEGINNING OF A SECTOR ADDRESS 
* FIELD OR A SECTOR DATA FIELD 


LDx 
Loop) LOA 
BPL 
CMP 
BNE 
Loop2 LDA 
BPEL 
cmp 
BNE 
LooP3 LDA 
BPL 
CMP 
BEQ 
BNE 


* ONCE ALIGNED, 


SLOT 
ORVRD,X WAIT FOR NEXT BYTE 

Loopl 

#SFE AUTOSYNC? 

Loopl NO, DON'T START IN MIDDLE 
DRVRD,X WAIT FOR NEXT BYTE 

LOOP2 

aSPF TWO AUTOSYNCS? 

LOOPL NOT YET 

DRVRD,X 

LooP3 

#SEE STILL AUTOSYNCS? 

LOOP3 YES, WAIT FOR DATA BYTE 
Loop4 ELSE, START STORING DATA 


BEGIN COPYING THE TRACK TO MEMORY. 


* coOPY AT LEAST TWICE ITS LENGTH TO INSURE WE GET IT 
* 


ALL. 


LOOPD CDA 
BPL 
Loce4 STA 
INC 
BNE 
INC 
BPL 
Lox 
LDA 


DRVRD,X WAIT FOR NEXT OATA BYTE 
LOOPD 

(PTR) ,Y STORE 1N MEMORY 

PTR BUMP POINTER 

LooPD 

OTR#L DONE $4000 BYTES YET? 
LOOPD NO, CONTINUE 

SLOT 

ORVOFF ,X TURN DRIVE OFF 


* WHEN FINISHED, OUMP SOME OF TRACK IN HEX ON SCREEN 


LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
JMP 


#>BUFFER DUMP 4800.4G6AF 

AlL 

#<BUFFER 

AlL+1 

#>BUPFER+SAFP 

A2L 

# <BUPFER+SAF 

A2L+1] 

XAM EXIT VIA HEX DISPLAY 


* RECALIBRATE ARM 


RECALC LDA 
STA 
LDA 
STA 
JSR 
LDX 
LOA 
LDA 
LDA 
LDA 
RTS 


#$36 PRETENT TO BE ON TRACK 48 
CURTRK 

#598 SELECT TRACK 06 

DESTRK 

ARMOVE GO THERE 

SLOT GET SLOT NUMBER 

DRVSMU,X TURN ALL PHASES OFF 
DRVSM2,X 

DRVSM4,X 

DRVSM6,X 


RETURN TO CALLER 
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209F: 142 * ARM MOVE ROUTINE 

209F:A9 86 144 ARMOVE LDA #560 

20A1:8D 09 28 145 STA FLAG INITIALIZE FLAG 

2GA4:AD 67 26 146 LDA CURTRK GET CURRENT TRACK 

20A7:38 147 SEC 

20A8:ED 66 26 148 sBc DESTRK SUBTRACT DESTINATION TRACK 
20AB:F@ 36 2063 149 BEQ DONE IF EQUAL THEN EXIT 
20AD:B@ G4 2683 «158 bcs OK POSITIVE RESULT? YES, GO ON 
2Q0AF:49 FF 1sl EOR #SFPF MAKE RESULT POSITIVE 
20B1:69 61 152 ADC #$01 

2083:38D 68 28 153 OK STA DELTA SAVE RESULT 

20B6:2E 69 20 154 ROL FLAG SET IN/OUT FLAG 

20B9:4E 07 26 155 LseR CURTRK ON ODD OR EVEN TRACK? 
2@BC:2E @9 26 156 ROL FLAG PUT RESULT IN FLAG 
20BF:GE 69 20 157 ASL FLAG ADJUST FOR TABLE OFFSET 
28C2:AC 89 20 158 LDY FLAG GET TABLE OFFSET 

20CS:B9 F8 20 159 LOOP LOA TABLE ,Y¥ GET PHASE TO TURN ON 
26C8:20 £4 20 168 JSR PHASE 

26CB:B9 F9 28 161 LDA TABLE+1,Y GET NEXT PHASE TO TURN ON 
20CE:26 £4 20 162 JSR PHASE 

2801:98 163 TYA 

2902:49 82 164 EOR #$02 ADJUST OFFSET 

28D4:A8 165 TAY 

20D5:CE 88 26 166 DEC DELTA DECREMENT NUMBER OF TRACKS TO 
2@D8:AD G8 28 167 LDA DELTA 

2@DB:00 E8 28CS 168 BNE LOOP IF NOT DONE, DO ANOTHER 
2BDD0:AD @6 28 169 LDA DESTRK UPDATE CURRENT TRACK WITH 
2GE@:8D @7 20 178 STA CURTRK WHERE THE ARM IS NOW 
20E3:690 171 DONE RTS CONE, RETURN TO CALLER 
2GE4: 173 * TURN A PHASE ON, WAIT THEN TURN IT OFE 

20£4:60 95 26 175 PHASE ORA SLOT ADD SLOT TO PHASE 

2QE7:AA 176 TAX 

2G6E8:BD 81 Cé 177 LDA DRVSM1,X TURN ON A PHASE 

2GEB:28 F2 26 178 JSR WAIT WAIT FOR ARM TO SETTLE 
20EE:BD 86 C& 179 LDA DRVSMG ,X TURN OFF PHASE 

26F1:60 186 RTS RETURN TO CALLER 

20F2: 182 * 28 MILLISECOND DELAY ROUTINE 

20F2:A9 56 184 WAIT LOA #$56 WAIT ABOUT 2@ MILLISECONDS 
26F4:20 AB FC 185 JSR DELAY 

2G0F7:66 186 RTS RETURN TO CALLER 

20F8: 188 * PHASE TABLE 

20F8:02 64 06 8d 190 TABLE DFB $62,$04,$06,806 

2GFC:86 64 62 8d 191 DFB $86,$04,$62,S08 

3C AlL 3E A2L 209F ARMOVE 4000 BUFFER 

2807 CURTRK FCA8 DELAY 2668 DELTA 2006 OESTRK 

26E3 DONE 2818 ORIVE] C888 DRVOFF C689 DRVON 

C@8C DRVRD C@8E DRVRDM CO8A DRVSL1 C688 DRVSMO 

C881 DRVSM1 C8982 DRVSM2 C684 DRVSM4 C@86 DRVSM6 
?2606 ENTRY 26809 FLAG 263D LOOP1 2646 LOOP2 

264F LOOP3 26C5 LOOP 205F LOOP4 285A LOOPD 

28B3 OK 2@E4 PHASE @@ PTR 2082 RECALC 

2065 SLOT 26GA START 26F8 TABLE 2663 TRACK 

2004 UNITNUM 20F2 WAIT FDB3 XAM 


*#* SUCCESSFUL ASSEMBLY := NO ERRORS 
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FORMAT—REFORMAT A RANGE OF TRACKS 


FORMAT can be used to selectively format a single track, a 
range of tracks or an entire diskette. While it is primarily meant to 
be educational, it can assist in repairing damaged diskettes. For 
example, if a single sector was damaged, it could be repaired by 
FORMATting the particular track on which it resides. To avoid 
losing data, all other sectors on the track should be read and copied 
to another diskette prior to reFORMATting. After FORMAT is 
run, they can be copied back to the repaired diskette and data can 
be written to the previously damaged sector. 

Note that FORMAT has very limited error handling 
capabilities; in addition, it may not work well on drives that are out 
of adjustment (too fast or slow). The method used to do the 
formatting, that of building an image of the track in memory and 
then writing that image to the diskette, is similar to the method 
used by “nibble” copy programs. 

To run FORMAT, store the starting track number at location 
$2003, the ending track number at location $2004, the volume 
number at location $2005, and the device number at location 
$2006, then begin execution at $2000. FORMAT will return to the 
monitor upon completion. If a track cannot be formatted for some 
reason (eg. physical damage etc.), an error will be indicated. For 
example: 


BLOAD FORMAT (Load the: FORMAT program) 
CALL -151 (Get into the monitor from BASIC) 


(Now insert the diskette to be FORMATted) 


2003:11 11 FE 68 N 2060G {Store an 11 (track 17) in $2083, 
store an 1l in $2004, store an FE 
(volume 254) in $2885, store a 60 
(slot 6 drive 1) in $2066, N 
terminates the store command, go to 
location $2609) 


A-10 Beneath Apple ProDOS 





The output might look like this: 


FORMATTING TRACK 22 


WARNING: FORMAT will destroy existing data on the diskette 
in the indicated drive without allowing the user an opportunity to 


abort the program. Be sure the diskette in the drive is the one you 
wish to FORMAT. 


2000: 
2008: 
2000: 
2000: 
2000; 
2006: 
2000: 


2600: 


2066: 
2680: 
2800; 
2006: 


2006: 


2080: 
2008: 
2608; 
2006: 
2066: 
2000: 
2880: 
2000: 


1 

NEXT OBJECT FILE 
2086 2 
4 

S 

6 

a 

8 

9 

18 

1h 

12 

2:3 

14 

15 

16 

17 

18 

19 

20 

21 

22 

24 

8808 26 
883C 27 
OO3E 28 
642 29 
31 

FC1@ 33 
FC58 34 
PCA8 35 
FCB4 36 
FCBA 37 
FDED 38 
FDDA 39 
FE2C 4@ 





NOW THAT 
A HIGH BIT! = 





O 


OF TRACKS. 


RR RK KR EI SOT RKO TORO II SIGIR ROR It 


FRITS IOI TOTO III Ot 


* PORMAT -- FORMAT RANGE 
NAME IS FORMAT.@ 
ORG $2682 
* 
* FORMAT: 
* 
* 
* INPUT: $2603 = 
* DEFAULT 
* $2004 = LAST TRACK TO 
= DEFAULT 
‘3 $2065 = VOLUME 
* OSFAULT 
$2006 = UNIT NUMBER 
id OEPAULT 
* 
* ENTRY POINT: $2800 
* 
* PROGRAMMER: PIETER LECHNER 5/19/84 
* 
* 
* ZPAGE DEFINITIONS 
PTR EQU $8 
Al EQU $3c 
A2 EQU S3E 
A4 EQU $42 
* MONITOR ROUTINES 
BS EQU SFC16 
HOME EQU $FC58 
DELAY EQU SFCA8 
NXTA4 EQU = SFCB4 
NXTAL EQU  SFCBA 
couT EQU $FDED 
PRBYTE EQU  SFDDA 
MOVE EQU SFE2C 


THIS PROGRAM WILL INITIALIZE A RANGE OF 
TRACKS WITH ANY VOLUME NUMBER DESIRED. 


FIRST TRACK TO BE INITIALIZED 


BE INITILIZED 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
ry 
* 
* 
* 
* 
® 
* 
* 


WORK POINTER 
MONITOR POINTERS 


BACKSPACE 

CLEAR SCREEN 

DELAY ROUTINE 
INCREMENT POINTERS 
INCREMENT POINTER 
CHARACTER OUTPUT 
HEX OUTPUT 

MOVE ROUTINE 


(A4/A1) 
(Al) 
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2u032 
2uc4a: 





L98u 
Cedi 
CUa2 
Coed 





CU39 
SUA 
2O5B 
LUBE 
LU8h 
CUBi 
CUOF 


22 
20 





2024230 


2W27:2u 
2U2ArAN0 
2021230 
2830:20 


2433: 


2033220 
203G:AD 
203960 
203C3A9 
20 3i24D 
20412A9 
2043230 
20462449 
20482610 
204: 38 
204C:Ab 
204F: £9 
2051380 
2054:AD 
2057289 
2059:8bD 





205F326 
2662320 
2065:298 
2068:20 


20 


42 8 ESR Ge 


S UKVSMYE 








3 ORV 
4 URVON 
DRVSLi 
2 ONVSL2 
3 vRVRO 
rd RVR 
95 DRVRGM 
6 GRVARM 


SRO*  PORMAT 
Ht FORMAL 

62 STRK 

63 ETRK 


64 VOLNUM 
65 UNITNUM 








Uuited 
Jildco 
¥CUGS 
SON69 
SOUSA 


Vd3 






SCvevd 
SCUBE 


sluer 


PROGRAM 


ht 


OFB 
OFB 
DER 
OPB 








360 


67 * RECAGLIBRATE ARM TO THE DESI 


69 ENTRY 


76 


74 DRIVEL 


39 *  SULLD 


cai 
2 
33 
94 
95 
96 
97 
98 
99 
108 LOGPRA 
1¢él 


118 
111 ANOTHER 


JSR 
LbA 
PHA 
AND 
STA 
TAX 
BLA 
BPL 
INX 
LDA 
Lox 
LDA 
LDA 
LOA 


JSR 
LoA 
OTA 
JSK 


PRACK 


JSR 
LDA 


OTA 
LDA 
OTA 
LUA 
STA 
LDA 





SCREEN 
UNITNOM 


B79 
SLOT 


URIVEL 


DRVSLI,X 
slot 
VEVON,X 
UORVRDM,X 
URVRD,X 


RECALC 
STRK 

OESTRK 
ARMOVE 





IMAGE EN MEMORY 


PT LOUDATA 





#505 
RETRYCNT 


#> D 
CUREND 

# SEND 
CUREND+ 





CUREND 
#2 IMAGE 
LENGTH 
CUREND#+ 1 
RIMAGE 
CENGT:t+1 
LENGT a 
FINDSTART 
BLOGAPL 
BLOTRK 
FEXTRK 








SinP Mga bog 


Se EVE OFF 
wi TV ON 
OKTVE 








LATC 
eRITE OATA LAT 
SEP KEAG dE 
SET wis 





SHEP OVER OATA 


VOLUME NUMBER 
UNIT NUMBER 


RED TRACK 


EAK SCREEN/D 
P UNIT NOMBE 
SAVE FOR LATER 
GET SLOT ONLY 





PUT SLOT IN X 
CHECK WHICH DR 







SELLE DRIVE 1 

SELECT DRIVE 2 

APPROPR 
SLOT 


TURN DRIVE ON 
INSURE READ MG 


RECALIBRATE AR 
GET STARTING TF 


GO THERE 


FILL DATA AREA 
INITIALTZE TRA 
INITIALIZE KET 
SAVE CURRENT L 
VE SECTOR IMAG 


CUMPUTE LENGTH 
CURRENT SECTOR 


COMPUTE START 
BUILD GAPI1 (12 
BULLD TRACK IM 
UPDATE ADDRESS 


IT LONG 


Hi 
CH 





ISPLAY MESSAGE 
R 


REG 
IVE TO USE 


TATE DRIVE 


DE 


M 
RACK 


WITH S96'°S 
CK NUMBER 
RY COUNT 
ENGTH 

E 


OF 
IMAGE 


OF TRACK {MAGE 
8 BYTES) 

AGE iN MEMORY 
INFO 


A-A2 
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206B: 


2068: 28 
2666: 20 
2071:B8 
2673:20 
2076:98 
2878:38 
2079:AD 
207C: £9 
207E:8D 
2081:AD 
2084:E9 
2686:8D 


2089:CE 
208C:10 


298E: 


208E:A9 
2690:08 
2092:A9 
2094:20 
2897:68 


2098:EE 
269B:AD 
2@9E:CD 
2@A1L:FO@ 
26A3:B8 
26A5:8D 
20A8:2¢ 
28AB:4C 


2@AE: 


2@AE:AE 
20B1:BD 
20B4:60 


2085: 


2085:A9 
20B7:85 
2@B89:AD 
28BC:85 
2@BE:AC 
20C1:AE 
20C4:38 
28C5:BD 
20C8:BD 
20CB: 38 
28CD:A9 
20CF:9D 
20D2:DD 


2@DS:EA . 


26D6:4C 
26D9:49 
26DB: EA 
26DC: EA 
2@D0:4C 
2080: 48 
20E1:68 
20E2:B1 
2@E4:C9 
2056 :98 
20£8:EA 
2069:9D 
28EC:DD 


2GEF:C8” 


23 

26 
2692 

21 
2098 


24 


24 
24 


24 
24 
2048 


24 
c@ 


26- 


26D9 


ce 
ce 


* INITIALIZE TRACK 


JSR 
JSR 
BCS 
JSR 
Bcc 
SEC 
LDA 
SBC 
STA 
LDA 
SBC 
STA 


DEC 
BPL 


PRTRK 
WRITE 
ERRORL 
VERIFY 
NEXT 


CUREND 
#562 
CUREND 
CUREND+1 
#500 
CUREND+1 
RETRYCNT 
LOOPA 


* ERROR OCCURED 


ERROR1 
ERR2 


NEXT 


LASTONE 


LDA 
BNE 
LDA 
JSR 
RTS 


INC 
LDA 
CMP 
BEQ 
BCS 
STA 
JSR 
IMP 


* WHEN DONE, 


FINISH 


LOX 
LDA 
RTS 


#$62 
ERR2 
#SO1 
ERRHDL 


TRACK 
TRACK 
ETRK 
LASTONE 
FINISH 
DESTRK 
ARMOVE 
ANOTHER 


EXIT 


SLOT 
DRVOFF ,X 


* WRITE MEMORY TO DISK 


WRITE 


ASYNC 


Loop. 


LOOP2. 


WRIT 


LDA 
STA 
LDA 
STA 
LbY 
LOX 
SEC 
LDA 
LDA 
BMI 
LDA 
STA 
CMP 
NOP 
JMP 
EOR 
NOP 
NOP 
JMP 
PHA 
PLA 
LDA 
CMP 
BCC 
NOP 
STA 
CMP 
INY 


#908 
PTR 
START+1 
PTR+L 
START 
SLOT 


DRVWR,X 
DRVRDM,X 
WPERR 
4SFE 
ORVWRM,X 
DRVRD,X 


Loop 
#$83 


WRIT 


(PTR) -Y 
#$88 
ASYNC 


DRVWR,X 
DRVRD,X 


PRINT TRACK NUMBER 
WRITE A TRACK 

WRITE PROTECT ERROR 
VERIFY THE TRACK 

IF OK DO ANOTHER 
ELSE ADJUST GAP SIZE 


DECREMENT RETRY COUNT 
IF OK TRY AGAIN 


PRINT ERROR MESSAGE 
EXIT PROGRAM 


INCREMENT TRACK NUMBER 
COMPARE WITH LAST TRACK TO DO 
IF EQUAL DO LAST ONE 

IF DONE THEN EXIT PROGRAM 


GO TO DESIRED TRACK 
GO BACK AND DO ANOTHER 


GET SLOT 
TURN DRIVE OFF 
EXIT PROGRAM 


POINT AT START OF DATA 


ASSUME ERROR 


CHECK WRITE PROTECT STATUS 


WRITE 1 $FF 


TURN HIGH BIT ON 


DELAY EXTRA 8 CYCLES 


GET BYTE TO WRITE 

IS IT "S¥NC" BYTE 

YES, THEN MAKE ADJUSTMENT: 
WRITE A BYTE 


INCREMENT OFFSET 
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20FG:08 
20F2:E6 
20F4:16 
20F6:BD 
20F9:BD 
20FC:18 
20FD: 60 


20FE: 


20FE:A9 
210608:85 
2102:A9 
2104:85 
2106:AG 


2108: 


2168:AE 
216B:BD 
21GE:18 
2116:C9 
2112:D06 
2114:80 
2117:16 
2119:C9 
211B:06 


2110: 
2110: 


2110:BD 
2120:16 
2122:91 
2124356 
2126:06 
2128:56 
212A:A5 
212C:C9 
212E:06 
2130:66 


2131: 


2131:290 
2134320 
2137:26 
213A:60 


213B: 


213B:18 
213C:A9 
213E:85 
2146:69 
2142:85 
2144:3A9 
2146:85 
2148:69 
214A:85 
214C:A9 
214E:8D 
2151:20 
2154:68 


BE 
@1L 
EC 
8E 
8c 


Fl 
39 


20E9 


2QE2 
ce 
co 


211D 


211D 


2110 


183 
184 
185 
186 
187 
188 
189 


191 


193 
194 
195 
196 
197 


199 


262 
202 
283 
284 
265 
266 
207 
288 
289 


211 
212 


214 
215 
216 
217 
218 
219 
226 
221 
222 
223 


225 


227 
228 
229 
236 


232 


234 
235 
236 
237 
238 
239 
246 
241 
242 
243 
244 
245 
246 


BNE LOOPL 
INC PTR+] 
BPL LOOP2 
LDA ORVRDM,X 
LDA DRVRD,X 
CLC 

WPERR RTS 


* PREPARE TO 


DUMP LDA #$080 
STA PTR 
LDA #$40 
STA PTR+1 
LDY #@ 


INCREMENT POINTER 


PUT IN READ MODE 


DUMP TRACK TO MEMORY 


POINT AT DATA 


* START DUMPING AS SOON AS TWO SYNC BYTES FOUND 


Lox SLOT 
LOOP3 LDA ORVRD,X 
BPL LOOP3 
CMP SFE 
BNE LOOP3 
Loop4 LDA ORVRD,X 
BPL Loop4 
CMP #SFF 
BNE LOoP3 


* ONCE ALIGNED, 


WAIT FOR NEXT BYTE 


AUTOSYNC? 
NO, DON'T START YET 
WAIT FOR NEXT BYTE 


TWO AUTOSYNCS? 
NOT YET 


BEGIN COPYING THE TRACK TO MEMORY. 


* COPY ENOUGH TO [INSURE WE GET IT ALL 


LOOPD LDA DRVRD,X 
BPL LOOPD 

LOOPS STA (PTR) ,¥ 
INC PTR 
BNE LOOPD 
INC PTR+L 
LDA PTR+1 
CMP #S6G 
BNE LOOPD 
RTS 


* READ SECTOR ZERO TO VERIFY 


VERIFY JSR DUMP 
JSR SETUP 
JSR COMPARE 
RTS 


* FILL DATA AREA WITH $96'S 


FILLOATA CLC 
LDA #>DATA 
STA Al 
ADC #>DATALTH 
STA A2 
LDA #<DATA 
STA Al+tl 
ADC #<DATALTH 
STA A2+1 
LDA #596 
STA BYTE 
JSR FILL 
RTS 


WAIT FOR NEXT DATA BYTE 


STORE IN MEMORY 
BUMP POINTER 


DONE $2000 BYTES YET? 


NO, CONTINUE 


FORMATTING 
DUMP TRACK TO MEMORY 


CHECK WHAT WE JUST WROTE 


SET Al TO DATA START 


SET Al TO DATA END 


INDICATE FILL BYTE 
CALL FILL ROUTINE 
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2155: 


2155:A6 
2157:AD 
215A:91 
215C: 26 
215F:96 
2161:66 


2162: 


2162248 


2164:AD 
2167:@A 
2168:2E 
216B:88 
216C0:16 


216E:8D 


2171238 
2172:A9 
2174:ED 
2177:8D 
217A3A9 
217C:3ED 
217F:8D 
2182:66 


2183: 


2183:18 
2184:AD 
2187:85 
2189:69 
218B:85 
218D:AD 
2196:85 
2192:69 
2194:85 
2196:A9 
2198:8D 
219B:20 
219E:60 


219F; 


219F:AD 
21A2:85 
21A4:AD 
21A7:385 
2LA9:A5 
21AB:85 
21AD:A5 
21AP:85 
21B1:A9 
21B3:80 
21B6:A0 
21B8:A9 
21BA:85 
21BC:A9 
21BE:85 
21C0:28 
21C3:CE 
21C6:198 
21C8:60 


ao 
CF 
3¢ 
BA 
F6 


93 
ey") 


Ol 


Fo 
be 


86 
oe 
b4 
7E 
Dl 
DS 


24 


FC 


24 
24 


24 


24 


24 


24 


24 


24 


2157 


248 


256 
251 
252 
253 
254 
255 


257 * COMPUTE 


* FILL MEMORY WITH A CONSTANT 


FILL 
Looe 


LoY 
LDA 
STA 
JSR 
BCC 
RTS 


259 FINDSTART LDY 


260 
261 
262 
263 
264 
265 


267 
268 
269 
276 
271 
272 
273 
274 


276 


278 
279 
2898 
281 
282 
283 
284 
285 
286 
287 
288 
289 
298 


292 


294 
295 
296 
297 
298 
299 
366 
301 
362 
363 
384 
365 
306 
367 
308 
369 
318 
31l 
312 


MORE 


LDA 
ASL 
ROL 
DEY 
BPL 
STA 


SEC 
LDA 
spe 
STA 
LOA 
SBC 
STA 
RTS 


* BUILD GAP) 


BLDGAPI 


* BUILD 


BLDTRK 


MORE2 


CLC 
LDA 
STA 
ADC 
STA 
LDA 
STA 
ADC 
STA 
LDA 
STA 
JSR 
RTS 


TRACK 


LDA 
STA 
LDA 
STA 
LOA 
STA 
LDA 
STA 
LDA 
STA 
Loy 
LDA 
STA 
LDA 
STA 
JSR 
OEC 
BPL 
RTS 


#$60 
BYTE 
(Al) ,Y 
NXTAL 
LOOP 


START OF TRACK IMAGE 


a#5@3 
LENGTH 
a 


LENGTH+1 


MORE 
LENGTH 


#588 
LENGTH 
START 
#S7F 
LENGTH+1 
START#1] 


INITIALIZE OFFSET 

GET BYTE TO USE 

STORE A BYTE 

CALL MONITOR INCREMENT 
LOOP UNTIL DONE 


MULTIPLY LENGTH BY 16 


SUBTRACT IT FROM $7F8@ 
TO FIND START 


AT START OF TRACK IMAGE 


START 
Al 
#S8 
A2 
START#1] 
Ale#l 
#$8B 
A2+l 
#S7E 
BYTE 
FILL 


SET Al TO START 


SET A2 TO START + $8@ 


USE $7F FOR SYNC BYTE 


CALL FILL ROUTINE 


IMAGE USING SECTOR IMAGE 


CUREND 
A2 
CUREND+1 
A2+1 

Al 

A4 

Al+l 
A4+) 
#SOF 
COUNT 
#$60 
#>1MAGE 
Al 

#< IMAGE 
Al+l 
MOVE 
COUNT 
MORE2 


SET A2 TO SECTOR IMAGE END 


SET A4 TO CURRENT POSITION 

IN TRACK IMAGE 

SET COUNT TO 16 

CLEAR Y FOR MOVE ROUTINE 

SET Al TO SECTOR IMAGE START 
MOVE SECTOR IMAGE TO TRACK IMAGE 


DECREMENT COUNT 
LOOP UNTIL WE HAVE 16 SECTORS 
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21C9; 


21C9:A9 
21CB:8D 
21CE:AD 
2101:85 
21D3:AD 
21D6:85 
21D8:A9 
21DA:85 
21DC:A9 
21DE:85 
21LE@: 26 
21£3:20 
21E6:EE 
21E9:AD 
21EC:C9 
21EE:D@ 
21F0:60 


21F1: 
21Fi: 
21FL1: 


21F1:A9 
21F3:85 
21PS:A9 
21F7:385 
21F9:A9 
21FB:85 
21FD:A9 
21FF:85 
2261:2¢ 
2204:A5 
2266:85 
2208:A5 
226A:85 
226C:AD 
226F:85 
2211:AD 
2214:85 
2216:A9 
2218:85 
221A:A9 
221C:85 
221E:20 
2221:66 


2222: 


2222:A0 
2224:A2 
2226:2¢6 
2229:Be 
222B:B1 
222D:0D 
2230:06 
2232:CA 
2233:198 
2235:2¢6 
2238:60 


2239; 


22393AG 
223B:B1 
223D:69 
223F:D1 
2241:D6 
2243:2¢8 
2246:98 


24 
24 


24 


22 
22 
24 
24 


22 


24 


24 


22 


FC 


24 


FC 


FC 


21E6 


2238 


2224 
2226 


224A 


2238 


314 


316 
31? 
318 
319 
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
330 
331 
332 


334 
335 
336 


338 
339 
346 
341 
342 
343 
344 
345 
346 
347 
348 
349 
356 
351 
352 
353 
354 
355 
356 
357 
358 
359 
366 


362 


364 
365 
366 
367 
368 
369 
37@ 
371 
372 
373 
374 


376 


378 
379 
386 
381 
382 
383 
384 


* FIX ADDRESS INFORMATION 
FIXTRK LbA #506 
STA SECTOR 
LDA START 
STA Al 
LDA START+1 
STA Al+l 
LDA #$60 
STA A2 
LDA #S$80 
STA A2+1 
AGAIN JSR POSITION 
JSR CMPADD 
INC SECTOR 
LDA SECTOR 
CMP #516 
BNE AGAIN 
RTS 


IN TRACK 


IMAGE 


START WITH SECTOR ULRO 


SET Al TO TRACK IMAGE START 


SET A2 TO $8008 


POSITION TO ADDRESS INFO 
UPDATE ADDRESS INFO 
NEXT SECTOR 


DONE ALL 16 YET? 
IF NOT DO ANOTHER 


* SET POINTERS FOR VERIFY ROUTINE 


* ON EXIT: Al > 1ST ADDRESS FIELD IN TRACK IMAGE 
by A4 > 1ST ADDRESS FIELD IN LIVE DATA FROM DISK 
SETUP LDA #S68 
STA Al SET Ai TO $4080 
LDA #546 
STA Alt] 
LOA #SGO 
STA A2 SET A2 TC $6000 
LDA #566 
STA A2+1 
JSR POSITION LOCATE IST AODRESS FIELD 
LDA Al 
STA A4 SET A4 TO POSITION FOUND 
LDA Al-+-1 
STA A4rl 
LDA START 
STA Al SET Al TO START OF TRACK IMA 
LDA STARTH+1 
STA Al+tl 
LDA #SFE 
STA A2 SET A2 TO S7FFE 
LOA #S7F 
STA A2tl 
JSR POSITION LOCATE 1ST ADDRESS FIELD 
RTS 


* LOCATE AN AODRESS FIELD 


POSITION Loy #500 
POS2 LDX #$82 
POS3 JSR NXTAL 
BCS CONE 
LDA (Al) -Y 
CMP TABLE,X 
BNE POS2 
DEX 
BPL POS3 
JSR NXTAl1 
DONE RTS 
* COMPARE TWO AREAS OF MEMORY 
COMPARE Loy 8S 
LoGec LDA (Al) ,Y 
ORA #S88 
CMP {A4),¥ 
BNE MISMATCH 
JSR NXTA4 
Bcc Loopce 


INITIALIZE OFFSET 
INITIALIZE COUNT 
INCREMENT POINTER 
IE PAST DATA THEN EXIT 


GET A BYTE 
CHECK IT IN TABLE 
NOT THERE, THEN TRY AGAIN 


FOUND ONE, COUNT IT 
GO UNTIL WE HAVE THREE 
POINT ONE PAST 


INITIALIZE OFFSET 
GET A BYTE (TRACK 
TURN 7E'S TO FF'S 
COMPARE WITH DISK 
EXIT ON MISMATCH 
INCREMENT BOTH POINTERS 
LOOP UNTIL DONE 


IMAGE) 


IMAGE 
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2248:18 385 cLe INDICATE SUCCESS 
2249360 386 RTS 

224A: 38 387 MISMATCH SEC INDICATE ERROR 

224B:660 388 RTS 

224¢: 290 * COMPUTE ADDRESS FIELD INFORMATION AND STORE IN TRACK IMAGE 
224C:AD 95 26 392 CMPADD LDA VOLNUM GET VOLUME NUMBER 
224F:20 6B 22 393 JSR COMPUTE COMPUTE AND STORE IT 
2252:AD D7 24 394 LDA ‘TRACK GET CURRENT TRACK 
2255120 6B 22 395 JSR COMPUTE COMPUTE AND STORE IT 
2258:AD DB 24 396 LDA SECTOR GET CURRENT SECTOR 
225B:28 6B 22 397 JSR COMPUTE 

225E:AD 65 26 398 LDA  VOLNUM 

2261:4D D7 24 399 EOR TRACK 

2264340 08 24 400 EOR SECTOR GET CHECKSUM 

2267:2@ 6B 22 481 JSR COMPUTE 

226A:68 462 RTS 

2268: 404 * NIBBLIZE A BYTE 

2268248 486 COMPUTE PHA SAVE A-REGISTER 

226C:4A 497 LSR A GABCDEFG H 

2260:09 AA 408 ORA #SAA 1A1C1E1G 

226F:91 3C 409 STA (Al) ,¥ STORE IT 

2271:68 416 PLA ABCDEFGH 

2272269 AA 411 ORA #SAA 1B1D1F1H 

2274:C8 412 INY 

2275:91 3C 413 STA  {Al),¥ STORE IT 

2277:C8 414 INY 

2278:60 415 RTS 

2279: 417 * RECALIBRATE DISK ARM 

2279:A9 30 419 RECALC LDA #$36 PRETEND TO BE ON TRACK 48 
227B:8D DA 24 420 STA CURTRK 

227E:A9 00 421 LDA #88 SELECT TRACK @@ 

2280:8D D9 24 422 STA DESTRK 

2283:2@ 96 22 423 JSR ARMOVE GO THERE 

2286:AE D6 24 424 LDX SLOT GET SLOT NUMBER 

2289:BD 86 Ce 425 LDA — DRVSMO,X TURN ALL PHASES OFF 
228C:BD 82 C8 426 LDA  DRVSM2,X 

228F:BD 84 CO 427 LDA DRVSM4,X 

2292:BD 86 C8 428 LDA DRVSM6,X 

2295:68 429 RTS RETURN TO CALLER 

2296: 431 * ARM MOVE ROUTINE 

2296:A9 00 433 ARMOVE LDA  #$9@ 

2298:8D DC 24 434 STA FLAG INITIALIZE FLAG 

229B:AD DA 24 435 LDA CURTRK GET CURRENT TRACK 
229E:38 436 SEC 

229F:ED D9 24 437 SBC DESTRK SUBTRACT DESTINATION TRACK 
22A2:FG 36 22DA 438 BEQ DONE2 IF EQUAL THEN EXIT 
22A4:B@ 94 22AA 439 BCS OK POSITIVE RESULT? YES, GO ON 
22a6:49 FF 440 EOR  #S$FF MAKE RESULT POSITIVE 
22A8:69 61 441 ADC = #$81 

22AA:8D DB 24 442 OK STA DELTA SAVE RESULT 

22AD:2E DC 24 443 ROL FLAG SET IN/OUT FLAG 

22BG:4E DA 24 444 LSR  CURTRK ON ODD OR EVEN TRACK? 
22B3:2E DC 24 445 ROL FLAG PUT RESULT IN FLAG 
22B6:GE DC 24 446 ASL FLAG ADJUST FOR TABLE OFFSET 
22B9:AC DC 24 447 LDY FLAG GET TABLE OFFSET 
22BC:B9 EF 22 448 LOOP6 LDA PTABLE, GET PHASE TO TURN ON 
22BF:2@ DB 22 449 JSR PHASE 

22C2:B9 FO 22 450 LDA PTABLE+1,¥ | GET NEXT PHASE TO TURN ON 
22C5:2@ DB 22 451 JSR PHASE 

22€8:98 452 TYA 

22€9:49 @2 453 EOR #$@2 ADJUST OFFSET 


22CB:A8 454 TAY 
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22CC:CE OB 24 455 DEC DELTA DECREMENT NUMBER OF TRACKS 
22CF:AD DB 24 456 LDA DELTA 

2202:D6 E& 22BC 0457 BNE LOOP6 IF NOT DONE, DO ANOTHER 
2204:AD D9 24 458 LDA DESTRK UPDATE CURRENT TRACK WITH 
2207:8D DA 24 459 STA CURTRK WHERE THE ARM IS NOW 
22DA:60 46@ DONE2 RTS DONE, RETURN TO CALLER 
2208: 462 * TURN A PHASE ON, WAIT THEN TURN IT OFF 

22DB:9D D6 24 464 PHASE ORA SLOT ADD SLOT TO PHASE 
22DE:AA 465 TAX 

220F:BD 81 Cé 466 LDA DRVSM1,X TURN ON A PHASE 
2282:26 ED 22 467 JSR WAIT WAIT FOR ARM TO SETTLE 
22E5:BD 88 Cé 468 LDA DRVSM6,X TURN OFF PHASE 

22E8:68 469 RTS RETURN TO CALLER 

22E9: 471 * 26 MILLISECOND DELAY ROUTINE 

22E9:A9 S6 473 WAIT LOA #556 WAIT ABOUT 28- MILLISECONDS 
22EB:28 A8 FC 474 JSR DELAY 

22EE: 60 475 RTS -RETURN TO CALLER 

22EF: 477 * PHASE TABLE 

22EF:62 @4 06 6¢ 479 PTABLE DFB $82,$84,586,S80 

22F3:66 64 62 60 48a OFB $86 ,$04,582,889 

22F7: 482 * CLEAR SCREEN AND DISPLAY MESSAGE 

22F7:2@ $8 FC 484 SCREEN JSR HOME CLEAR. SCREEN 

22FA:A9 EO 485 LDA #>MESSAGE 

22FC:85 68 486 STA PTR POINT AT MESSAGE 
22FE:A9 24 487 LDA #<MESSAGE 

2300:85 @2 488 STA PTR+1 

2382:2@ 33 23 489 JSR PRINT PRINT IT 

2385:68 496 Rts 

2306: 492 * PRINT TRACK NUMBER 

23063AD D7.24 494 PRTRK LDA TRACK GET TRACK NUMBER 
2369:28 DA FD 495 JSR. PRBYTE PRINT IT 

2306C:26 18 FC 496 JSR BS 

230F:2¢ 18 FC 497 JSR BS MOVE CURSOR BACK 
2312:66 498 RTS 

2313: 506 * ERROR HANDLER 

2313:C9 61 5@2 ERRHDL CMP #$61 1S if ERROR #1 

2315:D@ GA 2321 5863 BNE SECOND NO, THEN ASSUME €2 
2317:A9 F3 504 LDA #>MESSAGEL 

2319:85 06 565 STA PTR POINT AT MESSAGE 1 
231B:A9 24 506 LDA #<MESSAGE1] 

2310785 61 $87 STA PTR+1 

231F:08 08 2329 508 BNE PRINTIT ALWAYS TAKEN 

2321:A9 @9 589 SECOND LOA #>MESSAGE2 

2323:85 08 516 STA PTR POINT AT MESSAGE 2 
2325:A9 25 511 LDA #<MESSAGE2 

2327:85 @1 512 STA PTR+1 

2329:28 33 23 $13 PRINTIT JSR PRINT PRINT IT 

232C:AE D6 24 514 LOX . SLOT GET SLOT 

232F:BD 88 C@ $15 LDA DRVOFF ,X TURN ORIVE OFF 


2332360 "516 RTS EXIT PROGRAM 
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2333: 


2333:A8 
2335:B1 
2337:E8 
2339:20 
233C:C8 


233D:D8 
233F:66 


2346: 
2348: 
2348:D5 


2343: 

2343:AA 
2345:AA 
23473ARA 
23497ARA 


234B:DE 


234E:7F 
2351:7F 


2354:DS 


2357: 
23AD: 
24AD: 
24AE: 
24AE: 


24AE:DE 


24B1:7F 
24B4:7F 
24B7:7F 
24BA:7F 
24BO:7F 
24CO:7F 
24C3:7F 
24C6:7F 
24C9:37F 
24CC: 

24CC: 


24CC: 60 
24CE: 06 
24CF: 68 
24D6:06 
24D2:68 
24D4:08 
2406268 
2407268 
24D8 : 66 
2409268 
24DA: 88 
24DB: 60 
24DC:3008 
24D0:96 


24EG6: 

24E6:C6 
24F2:08 
24F3:80 
24F43D7 
2567287 


68 
ae 
86 
ED 


F6 


AA 


AA 
AA 
AA 
AA 
AA 


TE 
TF 


AA 


AA 
CF 


D2 
ag 


233F 
FD 


2335 


2348 
96 
2343 


EB 


7vF 
7E 


AD 
O56 
e186 
0981 


24AD 
#156 


24CB 
@18c 


DS 


D2 CD 


c9 D4 


$18 


* PRINT ROUTINE 


PRINT 
CHAR 


TERMINATE RTS 


* DATA AREA 


IMAGE 


HEADERI 


ADDRESS 
VOL 
TRK 
SEC 
CHK 


TRAILER 


GAP2 


HEADER2 


DATA 


DATAEND 
DATALTH 


TRAILER2 


GAP3 


END 
LEN 


COUNT 
RETRYCNT 
BYTE 
LENGTH 
CUREND 
START 
SLOT 
TRACK 
SECTOR 
DESTRK 
CURTRK 
DELTA 
FLAG 
TABLE 


MESSAGE 


MESSAGE] 


EQU 
DFB 


EQU 
DFB 
DFB 
DFB 
DFB 


OFB 


OFB 
DFB 


DFB 


DS 
Ds 
os 
EQU 
EQU 


DFB 


DFB 
OFB 
DFB 
OFB 
DFB 
DEB 
DFB 
DFB 
DEB 
EQU 
EQU 


DFB 
DFB 
DFB 
OFB 
OFB 
DFB 
OFB 
DFB 
DFB 
DFB 
DEB 
DFB 
DFB 
OFB 


MSB 
ASC 
DFB 
OFB 
ASC 
OFB 


#590 INITIALIZE OFFSET 
(PTR) ,¥ GET CHARACTER 
TERMINATE IF ZERO THEN EXIT 


CcouT PRINT CHARACTER 


CHAR DO ANOTHER 


* 


$D5,SAA,$96 


SAA,SAA 
SAA,SAA 
SAA, SAA 
SAA,SAA 


$DE,SAA,SEB 


S7EF,S7E,$7F 
S7F,S7F,S7F 


$D5,SAA,SAD 


$56 
$100 

$01 

#21 
DATAEND-DATA 


$DE,SAA,SEB 


S7E,S$7F,S7F 
S7F,S7E,S7F 
S7E,S7P,S7F 
$7E,$7E,S7E 
S7E,$7E,$7F 
S7E,$7F,S7F 
$7F,S7F,S7F 
S7F,S7E,S7TE 
S7E,$7F,S$7F 
#1 

END-IMAGE+1 


$60,S08 

$00 

$00 

$86,$60 

$86,560 

$88,S06 

$68 

$00 

$60 

$ee DESTINATION TRACK 

$o@ CURRENT TRACK 

$og NUMBER OF TRACKS TO MOVE 
$60 DIRECTION & ODD/EVEN FLAGS 
$96,SAA,$D5 


ON 

* FORMATTING TRACK ' 

$oe 

$80 

"WRITE PROTECT ERROR’ 
$87,$66 
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2569:8D 588 MESSAGE2 DFB $8b 


256A:D5 CE Cl C2 $89 ASC "UNABLE TO FORMAT’ 
251A:87 86 596 OFB $87,$88 
251C: $91 MSB OFF 

ZAP—DISK UPDATE UTILITY 


The next step up the ladder from DUMP and FORMAT is 
accessing data on the diskette at the block level. The ZAP program 
allows its user to specify a block number to be read into memory. 
The user can then make changes to the image of the block in 
memory, and subsequently use ZAP to write the modified image 
back over the block on disk. ZAP is particularly useful when it is 
necessary to patch up a damaged directory. Its use in this regard 
will be covered in more detail when FIB is explained. 

To use ZAP, store the number of the block you wish to access at 
$2007 and $2008. Store the least significant byte of the number in 
$2007 and the most significant byte in $2008. For example, the key 
block of the Volume Directory may be read by entering 2007:02 00. 
$2009 should be initialized with either $80 to indicate that a sector 
is to be read into memory, or $81 to ask that memory be written out 
to the block on the disk. You may also specify the disk drive to be 
used (slot 6, drive 1 is assumed) by storing a hex value of $s0 at 
$2004, where “s” is the slot to be used. If you wish to access drive 2° 
for a given slot, turn on the most significant bit in $2004 (e.g. slot 6, 
drive 2 would be 2004:E0). An example to illustrate the use of ZAP 
follows. 


CALL -151 (Get into the monitor) 
BLOAD ZAP (Load the ZAP program) 


(Now insert the diskette to be ZAPped) 


2007:92 68 88 N 2868G (Store a 2 (key block of the Volume 
directory) in $28087/8 and $8@ (read 
block) at $2009. N ends the store command 
and 2@8@G runs ZAP.) 
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The output might look like this... 


16600- 98 68 83 O68 FA 55 53 45 

-1008- 52 53.2E 44 49 53 4B 69 
1610- 68 G8 BG GB OB BB BO.BG 
1618- 66 68 O66 BB BG BB BO BB 
oo etc... 


In the example above, if the byte at offset 6 (the second character 
of the volume name, “USERS. DISK”) is to be changed to “O”, the 
following would be entered. 


1006:4F (Change +$@6 to S$4F ("0")) 
2009:81 N 2860G (Change ZAP to write mode and do it) 


Note that ZAP will remember the previous values in $2004 
through $2009. If something is wrong with the block to be read or 
written (an I/O error, perhaps), ZAP will print an error message of 
the form: 


RC=2B 
A return code of $2B, in this case, means that the diskette was 
write protected and a write operation was attempted. Other error 
codes are $27 (I/O error), and $28 (no device connected). Refer to 


the documentation on READ_BLOCK and WRITE_BLOCK in 
Chapter 6 for more information on these errors. 


s3s=5 NEXT OBJECT FILE NAME IS ZAP.S.@ 
@: 2086 


200 1 ORG $2686 

2000: 2 MSB ON 

2600 4 Pee PCRECCCCOCTCOSTCSSC£SCCCCS CS SSeS CSS Ce TPCT CPE TEESE TREES) 
2080 5% i 
2066 6 * ZAP: THIS PROGRAM WILL ‘ALLOW ITS USER TO READ/WRITE * 
2060 7 * INDIVIDUAL BLOCKS FROM/TO THE DISKETTE * 
2968 8 * 7 
2000 9 * INPUT: $2664 = UNIT NUMBER (DSSS06@0) 

2006 1a * DEFAULTS TO SLOT 6, DRIVE 1 ($68) 
2000: re ® (SLOT 6, DRIVE 2 IS SE@) ‘ 
2066 12 * $2005/6 = ADDRESS OF AREA IN MEMORY TO BE * 
2060 13 * READ/WRITTEN. . 
2068 14 * DEFAULTS TO $1000 . 
2000 is * $2667/8 = BLOCK NUMBER TO BE READ/WRITTEN * 
2008 16 * DEFAULTS TO $0960 hs 
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2000: 17 * $2069 = OPERATION TO BE PERFORMED:. * 
2080: 18 * $88 = READ BLOCK 7 
2000: 19 * $81 = WRITE BLOCK & 
2069: 26 * DEFAULTS TO READ BLOCK. * 
2608: 21 * . 
2660: 22 * ENTRY POINT: $2806 * 
2800: 23% * 
2896: 24 * PROGRAMMER: DON D WORTH - 2/25/84 7 
2808: 25% x 
2806: 26 fe te TOO ROI IO Rit i thik 
2606: 28 * FIXED LOCATIONS WE NEED 

2806: @23C 30 ALL EQU $3c MONITOR POINTERS 

2890: 6630 31 AlH EQU $3D 

2080: QG3E 32 A2L EQU $3E 

2606: @03F 33 A2H EQU $3F 

2698: BFOO 34 MLI EQU SBFOO MACHINE LANGUAGE INTERFACE 
2606; FDED 35 cout EQU SFDED MONITOR PRINT VECTOR 

2608: EDDA 36 PRBYTE EQU SFDDA MONITOR PRINT HEX BYTE 
2806: FDB3 37 XAM EQU SFDB3 MONITOR HEX DUMP SUBRTN 
2060: 39 * ENTRY POINT, JUMP AROUND PARMS 

2880:4C BA 20 41 ZAP JMP START BR AROUND DATA 

2663: 43 * MLI READ/WRITE BLOCK PARAMETER LIST 

2083:83 45 RWBLP OFB $83 PARM COUNT = 3 

2664:66 46 DFB $68 UNIT NUMBER 

2665:68 16 47 BUFF DW $1eee@ BUFFER ADDRESS 

2647:28 8G 48 Dw $eeee BLOCK NUMBER 

2089:80 49 OPER DFB $86 OPERATION TO BE PERFORMED 
206A: $1 * START OF CODE, CALL MLI 

26GA:AD 869 28 53 START LDA OPER PASS OPERATION CODE 
286D:8D 13 26 34 STA OP 

2816:28 66 BF 55 JSR MLI CALL MLI 

2613:06 S6 OP DOFB $8 

2614:03 26 $7 ow RWBLP 

2016:98 19 2831 58 BCC EXIT ALL WENT WELL??? 

2018: 69 * IF ERROR OCCURS, PRINT MESSAGE 

2018:48 62 PHA ; SAVE ERROR CODE 

2019:A9 87 63 LDA #$87 BEEP THE SPEAKER 

201B:286 ED FD 64 JSR couT 

2G1E:A9 D2 65 LDA #°R PRINT THE “RC=" 

2020:2@ ED FD 66 JSR cout 

2623:A9 C3 67 LDA #'C 

2625:28 ED FD 68 JSR COUT 

2028:A9 BD 69 LDA $= 

262A:2@ ED FD 76 JSR CcouT 

202D:68 7 PLA 

262E:4C DA FD 72 IMP PRBYTE PRINT THE HEX VALUE 

2631: 74 * WHEN FINISHED, DUMP SOME OF BLOCK IN HEX 

2631:18 76 EXIT CLC 

2632:AD 6S 28 77 LDA BUFF DUMP $2600-$28B7 

2035:85 3C 78 STA AlL 

2037:69 AF 79 ADC #SAE 

2039:85 3E 8d STA A2L 

263B:AD 96 28 81 LDA BUFF+1 

263E:85 3D 82 STA AlH 

28646:69 06 83 ADC #9 

2042:85 3F 84 STA A2H 


2644:4C B3 FD 85 IMP XAM EXIT VIA HEX DISPLAY 
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MAP—MAP FREESPACE ON A VOLUME 


The MAP program is written in BASIC and calls a tiny 
assembly language subroutine to read blocks from a ProDOS 
volume. It first reads the Volume Directory key block to determine 
the length and location of the Volume Bit Map. It then reads the bit 
map and prints a map of the volume’s freespace on the screen. 

Torun MAP against a disk volume, first LOAD the program into 
BASIC, place the disk to be MA Pped in slot 6, drive 1, and then 
RUN the program. The output from such a run might look like 
this: 


FREESPACE MAP FOR VOLUME /USERS.DISK/ 


UUUUUUUUU UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU 
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU 
UUUUUUUUUUUUUUUUUUUUUUUUUUUDUUUUUUUUUUUU 
UVUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU 
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU....... 


e@eeoteeseeneeneeeeeeseeeveev ee eeeeeeeaeeeeee eee 


U = USED BLOCK - = FREE BLOCK 


BLOCKS USED: 193 BLOCKS FREE: 87 


The MAP program first reads a short machine language 
program from data statements and pokes it into memory at $300. 
The machine language program is as follows. 


0300: PHA 7 SAVE REGISTERS UPON ENTRY 
0361: TYA 

6302: PHA 

6303: TXA 

0304: PHA 

0305: JSR SBF@@ CALL MLI 

8308: DFB $80 READ BLOCK CALL 
0309: DW $315 PARAMETERS AT $315 
O30B: STA $314 SAVE RETURN CODE 
O30E: PLA ; RESTORE REGISTERS 
O30F: TAX 

0318: PLA 

0311: TAY 


@312: PLA 
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0313: RTS ; AND RETURN TO BASIC PROGRAM 

G314: DOFB $88 RETURN CODE SAVED HERE 

@315: DFB $63 3 PARAMETERS 

0316: DFB $60 SLOT 6, DRIVE 1 

@3173 DW $480G BLOCK BUFFER IS AT $4608 

0319: OW i] BLOCK NUMBER FILLED IN BY BASIC PGM 


MAP then calls the subroutine (see lines 1000-1020) to read the 
Volume Directory key block (BN = 2). It obtains the length of the 
volume name from +4 (eliminating the $F0 entry type), and peeks 
the volume name and prints it on the screen from +5 in the buffer. 
If the total number of blocks on the volume (+41/42) is not 280, 
then the message “NOT A PRODOS DISKETTE” is printed. 
Otherwise, the first block of the Volume Bit Map is read. A loop is 
then entered (lines 365-440) where each binary bit which is one in 
the bit map is counted and printed as a “.” (free) and each that is 
zero is counted and printed as a “U” {in use). The totals for used 
and free blocks are then printed and the program exits. If an 
error occurs, it is printed in decimal and the program aborts 
execution. Possible errors are 39 (I/O error) and 40 (no device 
connected). 

MAP will not currently work for volumes with more or less than 
280 blocks but this can be easily changed by the reader. 


GANA NG 
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10 REM 
20 REM THIS PROGRAM PRINTS A MAP OF 
38 REM A PRODOS DISKETTE VOLUME. 


40 REM 
58 REM PROGRAMMER: DON D WORTH 2/22/84 
66 REM 


78 DATA 72,152,72,138,72,32,0,191,128,21,3,141,280,3,104,176,164,168 


75 DATA 164,96,0,3,96 

80 REM ; 

98 REM POKE BLOCK READ SUBROUTINE INTO MEMORY 
95 REM 

108 SB = 768: REM SB=ADDR OF SUBROUTINE 
105 BF = 16384: REM BUFFER IS AT $4606 
116 FOR I = SB TO SB + 22 

126 READ X: POKE I,X 

130 NEXT I 

148 POKE 1,@: POKE I + 1,BF / 256 

15@ BN = SB + 25:RC = SB + 26 

166 REM 


0 


1760 REM READ THE VOLUME DIRECTORY KEY BLOCK TO FIND THE BIT MAP 


190 REM 
260 POKE BN,2 
21@ GOSUB 160¢ 


230 REM 
240 REM PRINT THE VOLUME NAME 
256 REM 


260 L = PEEK (BF + 4) - 246 

265 HOME : PRINT “FREESPACE MAP FOR VOLUME /"; 
276 FOR I= 1 TOL 

288 PRINT CHRS ( PEEK (BE + I + 4)); 

298 NEXT I 

368 PRINT “/": PRINT 


318 REM 

32@ REM LOCATE AND READ BIT MAP BLOCK 

33@ REM 

348 IF PEEK (BF + 41) + PEEK (BF + 42) * 256 < > 286 THEN PRINT 
(7); "NOT A PRODOS DISKETTE": END 

35@ POKE BN, PEEK (BF + 39): POKE BN + 1, PEEK (BF + 498) 

36@ GosUB igae 

362 REM 

363 REM PRINT BIT MAP 

364 REM 

365 U = @:F = @ 

376 FOR B = @ TO 34 

386 X = PEEK (B + BF) 

396 FOR I = 1 T0 8 

406 IF X > = 128 THEN X = X - 128: PRINT ".";:F = F + 1: GOTO 420 


416 PRINT “U"7:U = U + 1 
420 X= xX * 2 
430 NEXT I 


440 NEXT B 

442 > REM 

443 REM FINISH UP 

444 REM 

456 PRINT PRINT : PRINT “U2USED BLOCK «*FREE BLOCK" 


455 PRINT : PRINT “BLOCKS USED: ";U;" BLOCKS FREE: °;F 
460 END 


1083 REM 
1001 REM READ A BLOCK FROM DISK 
1682 REM 


1003 CALL SB 
1016 IF PEEK (RC) = @ THEN RETURN 
1820 PRINT "1/0 ERROR = "; PEEK (RC); CHRS (7): END 


CHRS 
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FIB—FIND INDEX BLOCK UTILITY 


From time to time one of your diskettes will develop an I/O error 
smack in the middle of a directory. When this occurs, any attempt 
to use the files described by that directory will result in an I/O 
ERROR message from ProDOS. Generally, when this happens, the 
data stored in the files on the diskette is still intact; only the 
pointers to the files are gone. If the data absolutely must be 
recovered, a knowledgeable Apple user can reconstruct the 
directory from scratch. Doing this involves finding the index 
blocks for each file, and then using ZAP to patch a directory entry 
into the Volume Directory for each file which is found. FIB isa 
utility which will scan a disk volume for index blocks. Although it 
may flag some blocks which are not index blocks as being such, it 
will never miss a valid index block. Therefore, after running FIB, 
the programmer must use ZAP to examine each block printed by 
FIB to see if it is really an index block. Additionally, FIB will find 
every index block image on the volume, even some which were for 
files which have since been deleted. Since it is difficult to’ 
determine which files are valid and which are old deleted files, it is 
usually necessary to restore all the files and copy them to another 
diskette, and later delete the duplicate or unwanted ones. 

To run FIB, simply load the program and start execution at 
$2000. FIB will print the block number of each block it finds 
which bears a resemblance to an index block. For example: 


CALL -151 (Get into the monitor) 
BLOAD FIB (Load the FIB program) 


(Now insert the disk to be scanned into Slot 6, Drive 1) 
208GG (Run the FIB program on this diskette) 


The output might look like this... 


BLK=6068 BLK=8699 
BLK=8627. BLK=@0@AF 
BLK=0@28 BLK=@@B1l 
BLK=@63C BLK=80B4 
BLK=@06F BLK=90B7 


BLK=9997 
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Here 11 possible files were found. Of course, if some of the lost 
files were seedlings, they will not be represented here (seedlings 
are very difficult to locate once their directory entry is gone). And 
if some files were tree files, then three or more of the above block 
numbers could refer to index blocks for a single file. Also, if only 
one of several directories for a volume is damaged, some of the 
block numbers given may refer to files whose directory entries are 
still intact. If, after running FIB, you get an error message (RC = 
xx, see ZAP errors), you may need to reformat the offending track. 
Divide the block number by eight to determine which track has the 
error. An alternative is to use ZAP to copy all blocks without 
errors to another formatted disk and write zeroes on the blocks 
corresponding to I/O errors. In this way you can preserve 
undamaged blocks which are on the same track with damaged 
ones. 

In the example above, ZAP should now be used to read block 8. 
At +$00 and +$100 are the LSB and MSB of the block number for 
the first data block of the file (assuming this is not the master 
index block for a tree file). This block can be read and examined to 
try to identify the file and its type. Usually a BASIC program can 
be identified (even though it is stored in tokenized form) from the 
text strings contained in the PRINT statements. An ASCII 
conversion chart (see page 16 in the Apple IT Reference Manual for 
ITe Only) can be used to decode these character strings. Straight 
TXT type files will also contain ASCII text, with each line 
separated from the others with $0Ds (carriage returns). BIN type 
files are the hardest to identify and recover since their original 
address and length attributes were lost along with the directory 
entry. If you cannot identify a file, assume it is BAS (Applesoft 
BASIC). If this assumption turns out to be incorrect, you can 
always go back and ZAP the file type in the directory to try 
something else. Given below is an example ZAP to the Volume 
Directory to create an entry for the file whose index block is BLK = 
0008. This ZAP assumes that the Volume Directory itself was lost 


THATS A BIT 
RIDICULOUS! 


[D} 


C2 CA 
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and that you are starting the entire volume from scratch. Do not 
perform this patch to a diskette which is only partially 
damaged as you will wipe out the remainder of the valid 
directory entries in the process. 


CALL -151 
BLOAD ZAP 


(insert disk to be ZA Pped) 


1608:98 N 1601<1900.11FEM (Zero entire block of memory) 
10600:88 @@ G3 @@ FS 46 49 58 (Store a dummy Volume Directory 
1¢08:55 58 header for volume /FIXUP) 


1820:00 88 C3 27 @D BB BB BE 
1928:06 18 61 


1@2B:24 46 49 4C 45 (Make sapling entry for “FILE") 
183B:FC {file is type BAS) 

183C:88 @@ {key block is 8) 

1@46:08 xx 88 (EOF mark, see below) 

1849:E3 (full access “unlocked") 
164A:01 68 (AUX TYPE = $801 for BAS file) 
1650:62 o¢ (header pointer) 

2687:82 66 81 N 28386G (write new block image out as 


first Volume Directory block) 


The “xx” above should be set to the number of non-zero block 
numbers found in the index block as a first cut at the end of file 
mark. If garbage is loaded at the end of the program, try a smaller 
number. You may be able to deduce the true EOF by examining 
the program image on disk. Remember that AUX_TYPE will be 
different for different file types. See Chapter 4 for more 
information. 

As soon as the entry is created using the above procedure, the file 
should be immediately copied to another diskette. Do not attempt 
to use the file in place because the Volume Bit Map has not been 
updated and several other fields in the directory entry have been 
omitted. Also, you do not want to risk damaging other “lost” files 
on the disk. Repeat the above process for each index block found by 
FIB. As each file is recovered, it may be RENAMEzd to its original 
name on the new diskette. Once all the files have been copied to 
another disk, and successfully tested, the damaged disk may be 
re-initialized. 
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-o3ee NEXT OBJECT FILE 


208A:28 97 28 
296D:BG@ 35 
206F:AD 29 18 
2012:8D ED 28 
2615:AD 2A 16 
2618:8D EE. 20 
201B:4A 
201C34A 
201D:4A 
2@1E:4A 
201F: 38 
2020:6D 27 16 
2623:8D £9 20 
2626:80 EB 28 
2029:A9 06 
262B:6D 28 10 
262E:8D EA 26 
2031:8D EC 20 


2834: 


2034:AD EA 26 


2037:CD EE 20 
263A:D8 13 
263C:AD ED 26 


203F:CO ED 28 
2042:0@ 6B 
2044:68 
2845:EE E9 28 
2048:D8-EA 
2G4A:EE EA 20 
2640:D@ ES 


2809 


6248 
1000 
Bree 
FDED 
FDDA 
FDB3 


1829 
1027 


2G4F 


264F 


2634 


2834 


Ne 


NAME IS FIB.S.@ 
ORG $2000 
MSB ON 


SORT RK RK RRS RTT IRAE EEE EKER 


* * 
* PIB: THIS PROGRAM SCANS AN ENTIRE VOLUME, SEARCHING * 
* FOR WHAT APPEAR TO BE INDEX BLOCKS AND PRINTS * 
« THE BLOCK NUMBER OF EACH ONE IT FINDS. FIB WILL* 
* WORK FOR ANY SIZED VOLUME. SLOT 6, DRIVE 1 IS * 
* ASSUMED. * 
* * 
* INPUT: NONE * 
* * 
* ENTRY POINT: $2000 * 
* * 
* PROGRAMMER: DON D WORTH - 2/25/84 * 
* * 
PPR RS RSSRR SASS SA SAE ESE RE RES ERE SERRE SESE SESE ESE SRSA SESE EE SD 
* FIXED LOCATIONS WE NEED 
PTR EQU $48 WORK POINTER 
BUFFER EQU $1086 BLOCK BUFFER 
MUI EQU SBF OB MACHINE LANGUAGE INTERFACE 
cout EQU  $FDED MONITOR PRINT VECTOR 
PRBYTE EQU -S$EDDA. MONITOR PRINT HEX BYTE 
XAM EQU = $FDB3 MONITOR HEX DUMP SUBRTN 
* OFFSETS INTO VOL DIR HEADER 
TOTBLK EQU. $1029 
BITMAP EQU $1627 
* ENTRY POINT, READ VOLUME DIRECTORY HEADER 
FIB CDA #2 BLOCK = 2 

STA BLOCK 

LDA #6 

STA BLOCK#1 

JSR READ READ VOL DIR BLOCK 

BCS EXIT IF ERROR, GIVE UP RIGHT NOW 

LDA  TOTBLK 

STA LAST 


LDA TOTBLK+1 
STA LAST+1 


LSR A COMPUTE TOTBLK/ 4096 
LSR A 

LSR A 

LSR A FOR NUM BIT MAP BLOCKS 


SEC ; AND ADD ONE TO THAT 
ADC BITMAP 
STA BLOCK 
STA FIRST 


LDA #6 
ADC BITMAP+1 
STA BLOCK+1) POINT PAST THE BITMAP 
STA FIRST+1 
i SEE IF WE ARE AT END OF VOLUME 
NEWBLK LDA BLOCK+1 WHEN WE REACH LAST BLOCK +1 


CMP LAST+1L 
BNE READIT 
LDA BLOCK 


CMP LAST 

BNE READIT 
EXIT RTS XIT TO SYSTEM 
NXTBLK INC BLOCK INCREMENT BLOCK COUNT 


BNE NEWBLK 
INC BLOCK+1 
BNE NEWBLK AND CONTINUE LOOP 
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264F: 8 ed READ BLOCK AND CHECK FOR VALIDITY AS AN INDEX BLOCK 
2G04F:28 97 26 75 READIT JSR READ READ THIS BLOCK 

2052:BB FL 2045 76 BCS NXTBLK ERROR? 

2054:A0 30 78 LOY #0 

2056:B9 80 1G 79 CHKNGL LOA BUFFER,Y MAKE SURE ITS NOT ALL ZERO 
2059:19 06 ll 86 ORA BUFFER+$106,¥Y 

205C:Dd OS 2663 81 BNE CHKNG2 

205E:C8 82 INY 

265F:00 FS 2056 83 BNE CHKNGL 

2661:F@ E2 2645 84 BEQ NXTBLK IF SO, SKIP IT 

2663:AG OB 86 CHKNG2 CLoY #8 

2065:B9 68 10 87 CHKING LDA BUFFER,Y ALLOW ZERO ENTRIES 

2668:086 @5 2G6F 88 BNE COMPR 

266A:B9 68 11 89 LDA BUFFER+$16@,¥Y 

2G6D:FO OE 27D 96 BEQ BLKOK 

206F:A2 08 91 COMPR LOX #0 CHECK AGAINST FIRST 
2671:28 86 20 92 JSR CMP DO 16 BIT COMPARE 

2074:98 CF 2645 93 BCC NXTBLK TOO SMALL FOR BLOCK NUMBER 
2876:A2 G2 94 LDX #2 CHECK AGAINST LAST 

2078:20 86 26 95 JSR CMP 

207B:B® CB 2045 96 BCS NXTBLK TOO LARGE FOR BLOCK NUMBER 
2870:C8 97 BLKOK INY 

2Q07E:08 ES 2065 98 BNE CHKING 

2088:28 BE 26 186 JSR PBLOCK FOUND ONE, PRINT BLOCK NO. 
2083:4C 45 2¢ 181 IMP NXTBLK THEN CONTINUE 

2086: 183 * CMP: 16 BIT COMPARE 

2086:B9 @@ 11 165 CMP LDA BUPFER+$198,¥ CHECK MSB 

2689:0D EC 28 186 CMP FIRST+1,xX 

298C:98 98 2496 187 Bcc RTS ITS SMALLER 

268E:D@ 86 2096 168 BNE RTS ITS BIGGER 

2690:B9 68 16 169 LDA BUFFER,Y CHECK LSB 

2693:DD EB 2@ 116 CMP FIRST,X 

2896268 1ll RTS RTS 

2097: 113 * READ A BLOCK FROM DISK TO $1088 

2097326 O0@ BF 115 READ JSR MLI CALL MLI 

209A:8@ 116 DFB $8o READ CALL 

209B:E5 28 117 ow RWBLP 

209D:B@ 61 2@AS 118 BCS ERROR ERROR? 

209F:60 119 RTS 

20AG6: 121 * IF ERROR OCCURS, PRINT MESSAGE 

2GA0:48 123 ERROR PHA ; SAVE ERROR CODE 

20A1:A9 87 124 LDA #$87 BEEP THE SPEAKER 

20A3:20 ED FD 125 JSR CcouT 

26A6:A9 D2 126 LDA #'R PRINT THE "RC="“ 

20A8:26 ED FD 127 JSR cout 

20AB:A9 C3 128 LDA #'c 

26AD:2@ ED FD 129 JSR CcouT 

20B6:A9 BD 130 LDA #'= 

20B2:28 ED FD 131 JSR court 

20B5:68 132 PLA 

20B6:28 DA FD 133 JSR PRBYTE PRINT THE HEX VALUE 
26B9:A9 AQ 134 LDA #SAG PRINT A BLANK 

2088:2@ ED FD 135 JSR cout & FALL THRU TO PRINT BLOCK 
2Q0BE: 137 * PRINT CURRENT BLOCK NUMBER 

2GBE:A9 C2 139 PBLOCK LDA #'B PRINT "BLK=" 

28C8:26 ED FD 146 JSR couT 

28C3:A9 CC 141 LDA #'L 


28C5:26 ED FD 142 JSR cout 
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20C8:A9 CB 143 LDA a#'K 

26CA:2@ ED FD 144 JSR COUT 

26CD:A9 BD 145 LOA #*= 

20CF:20 ED FD 146 JSR COUT 

28D2:AD FA 28 147 LOA BLOCK+1 PRINT BLOCK NUMBER IN HEX 
2605:2@0 DA FD 148 JSR PRBYTE PRINT MSB 

20D8:AD ES 26 149 LDA BLOCK 

2@DB:2@ DA FD 15@ JSR PRBYTE AND LSB 

20DE:A9 8D 151 LDA #$8D 

2@E@:26 ED FD 152 JSR cout NEW LINE 

2G0E3:38 153 SEC 

20E4:60 154 RTS 

2GE5: 156 * MLI READ/WRITE BLOCK PARAMETER LIST 

20E5:63 158 RWBLP OFB $63 PARM COUNT = 3 

20£6:68 159 UNIT DFB $69 UNIT NUMBER 

20E7:08 108 16@ BUFF Ow BUFFER BUFFER ADDRESS 

20E9:06 26 161 BLOCK Ow $8988 BLOCK NUMBER 

2GEB:08 86 163 FIRST DW $8520 FIRST BLOCK AFTER BIT MAP 
26ED:08 86 164 LAST Ow $9680 LAST BLOCK ON DISK #1 


TYPE—TYPE COMMAND 


The TYPE program is an example of how to add commands to 
the ProDOS BASIC Interpreter. TY PE may be installed as a 
command by BRUNning TYPE or using the “—” smart RUN 
command. Once installed, the user may enter: 


TYPE filename[,Sslot][,Ddrive] 


The BI will not recognize “TYPE” as one of its commands and 
will pass control to the installed external command handler. The 
handler will locate and open the file, read its contents and print 
them on the sereen or output device. The user may suspend the 
listing with any keypress and resume it with any other. A control- 
C will abort the listing. 

TYPE’s operation begins when it is BRUN. Its first task is to 
allocate a page of memory between the BI and its buffers. It will 
copy the resident part of its program into this page. TYPE next 
stores the address of the newly allocated page in the BI’s 
EXTERNCMD vector in the BI Global Page. Each time the BI 
sees a command it doesn’t recognize, it will call the address in the 
EXTERNCMD vector before treating it as an invalid command. 
The transient portion of TYPE finishes up by copying and 
relocating the fixed addresses in the resident portion up to its new 
home in the newly allocated BI buffer. The transient portion then 
exits to ProDOS. 
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When an unknown command line is encountered, control passes 
to the resident code at TYPENT. TYPENT compares the 
command to the string “TYPE”, and if there is a match, it claims 
the command and returns to the BI to allow it to parse the filename 
and any other keywords given. If no SYNTAX ERROR occurs, 
control returns from the BI at the label TY PBAK. (If TY PENT 
does not recognize the command, it passes control on to the original 
contents of EXTERNCMD, in case there are other external 
command handlers installed.) When control returns to TY PBAK, 
the MLI is called to open the file, using the BI’s General Purpose 
buffer at HIMEM for an I/O buffer. The file is then read, 256 bytes 
at a time using $200 for a data buffer, and its contents are copied to 
the COUT screen output vector. At End of File, TYPENT exits to 
the BI through the MLI CLOSE function call. 

TYPE may be used as a model for small command handlers. It is 
written in such a way that it may coexist with numerous other 
external command handlers by preserving the original value it 
finds in the EXTERNCMD vector. Suggestions for additional 
external commands might include a file COPY command or a file 
hex/ASCII DUMP command. Note that if the installed, resident 
portion is longer than 256 bytes, the relocation code will have to be 
rewritten and will be a bit more complex. 


w-o5- NEXT OBJECT FILE NAME IS TYPE.S.@ 
2080: 2969 ORG $2068 


TYPE: WHEN BRUN, THIS PROGRAM INSTALLS AN EXTERNAL 
PRODOS BASIC INTERPRETER COMMAND BETWEEN THE 
BI AND ITS BUFFERS. THE NEW COMMAND IS 
INVOKED AS FOLLOWS: 


TYPE <PATHNAME>([,S#] [,D#] 


* 
* 
* 
* 
* 
* 
* 
7 THE TYPE COMMAND COPIES THE CONTENTS OF THE 
* INDICATED FILE TO THE SCREEN. 
« 
* 
* 
* 
* 
« 
* 


THE RESIDENT PORTION OF THE TYPE COMMAND 
REQUIRES ONLY 256 BYTES OF RAM. 


1 
3 
4 
S 
6 
7 
8 
9 
16 
ll 
12 
2000: 13 
14 
15 
16 
7 
18 PROGRAMMER: DON OD WORTH - 2/21/84 
19 
26 


Wee tk tok tek tT ti ttt tat RR RR TR RRR Aa RK 


RRR RRR RRR KR KERR ERE EERIE ERE ee 


* 
* 
* 
* 
* 
* 
* 
& 
* 
* 
* 
* 
* 
* 
* 
* 
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2060: 22 * FIXED LOCATIONS WE NEED 

2060: 9048 24 PTR EQU $48 WORK ZPAGE POINTER 

2600: 6673 25 HIMEM EQU $73 HIMEM (START OF GP BUFFER) 
2000: 6266 26 IN EQU $288 INPUT LINE BUFFER 

2608: BFOG 27 MLI EQU  SBFO6 MACHINE LANGUAGE INTERFACE 
2808: Cosa 28 KBD EQU S$COBe KEYBOARD LATCH 

2008: C016 29 KBDSTB EQU = $CB1B KEYBOARD CLEAR STROBE 
2006: FDED 38 COUT EQU  S$FDED MONITOR PRINT VECTOR 
2006: 32 * SELECTED THINGS FROM THE BI GLOBAL PAGE 

0800: 34 DSECT 

BEGG: BE@@ 35 ORG S$BEGO START OF BI GLOBAL PAGE 
BEGO:4C 08 60 37 BIENTRY JMP $0600 WARM ENTRY INTO PRODOS BI 
BE@3:4C 60 66 38 DOSCMD JMP $8660 COMMAND EXECUTER 

BEQ6:4C 98 6@ 39 EXTCMD JMP $6800 EXTERNAL COMMAND VECTOR 
BE@9:4C 68 66 48 ERROUT IMP $8606 EXIT WITH ERROR 

BEGC:4C 60 G6 41 PRNTERR JMP $0007 PRINT ERROR MESSAGE 

BEGF: 69 42 ERRCODE OFB &@ ERROR CODE 

BES@: BES@ 44 ORG S$BE5@ 

BE56:30 60 45 XTADDR DW $6068 EXEC ADDR OF EXTERNAL CMD 
BES2:98 46 XLEN OFB @ LENGTH OF CMD STRING -1 
BES3:08 47 XCNUM DFB @ BI COMMAND NUMBER 

BES4: @061 49 FNL EQU $@l FILE NAME EXPECTED 

BES4: 0004 58 SD EQU $64 SLOT/DRIVE PERMITTED 
BES4:08 60 $1 PBITS DW @ ALLOWED PARAMETERS BITS 
BE56:908 @8 52 FBITS ow g PARAMETERS FOUND BITS 
BE6C: BE6C 54 ORG $BE6C 

BE6C:48 9@ 55 VPATHL OW $6e90 ADDR OF PATHNAME 1 BUFFER 
BEGE:69 06 56 VPATH2 ow $600 ADOR OF PATHNAME 2 BUFFER 
BE76: BE79 $8 GOSYS EQuU) * MLI CALL HANDLER 

BECB: BECB 69 ORG §BECB 

BECB: 43 61 SOPEN OFB $83 OPEN PARAMETER LIST 

BECC:99 99 62 ow goo 

BEce ioe cr) 63 OSYSBUF DW $3388 BUFFER ADDR 

BED@:80 64 OREFNUM DFB $69 REF NUM RETURNED 

BEDS: BEDS 66 ORG SBEDS 

BEDS: BEDS 67 SREAD EQU * READ/WRITE PARM LIST 
BEDS: BEDS 68 SWRITE EQU * 

BED5:04 69 DFB $@4 PARM COUNT = 4 

BED6:68 76 RWRFNUM DFB $86 REFNUM 

BED7:06 0G 71 RWDATA DW $6000 BUFFER ADDR 

BED9:09 6G 72 RWCOUNT DW $8086 REQUEST LENGTH 

BEOB:@9 0@ 73 RWTRANS OW $080 TRUE LENGTH 

BEDD: BEDD 75 SCLOSE EQU) * CLOSE/FLUSH PARM LIST 
BEDD: BEDD 76 SFLUSH EQU * 

BEDD:¢1 77 DFB $61 PARM COUNT = 1 

BEDE: 90 78 CFRFNUM DFB Soe REFNUM 

BEFS: BEFS 88 ORG SBEFS 

BEFS:4C 68 06 81 GETBUFR JMP $eoeo ALLOCATE BI BUFFER 

2666; 83 DEND 

2008: 85 * THIS PART OF THE PROGRAM GETS CONTROL WHEN THE 
2600: 86 * BRUN COMMAND IS ISSUED. IT RELOCATES THE RESIDENT 
2800: 87 * PART OF THE CODE TO THE TOP OF MEMORY 

2060:A9 @1 89 TYPE LDA #1 WE NEED 1 PAGE 

2062:28 FS BE 98 JSR  GETBUFR BUY MEMORY FOR RESIDENT CODE 


2085:98 16 2617 91 BCC GOTBUF GOT IT 
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2087:A0 88 93 LDY +0 

2669:B9 76 20 94 ERLP LDA MSG,Y NO. BUFFER, PRINT MESSAGE 
286C:26 ED FD 95 JSR couT 

200F:C8 96 INY 

2018:C9 8D 97 CMP #$8D 

2@12:06 FS 2669 98 BNE ERLP 

2014:4C 08 BE 99 EXIT JMP BIENTRY AND LEAVE 

-2017:85 49 161 GOTBUF STA PTR+1 PTR --> BUFFER 

2619:AE 68 BE 162 LDX EXTCMD+ 2 

281C:8D 98 BE 163 STA EXTCMD+2 EXTCMD --> BUFFER 
2G1F:8E 40 21 104 STX NXTCOM+2 

2022:AE 67 BE 105 LDX EXTCMD+1 BUT SAVE OLD EXTRNCMD VECTOR 
2625:8E 3F 21 106 STX NXTCOM+1 

2028:A8 80 187 LDY #9 

282A:84 48 168 STY PTR 

202C:8C 67 BE 169 STY EXTCMD+1 

2G2F:89 6G 21 ill COPY LDA TYPENT,Y COPY RESIOENT CODE TO BUFFER 
2G32:91 48 112 STA (PTR) ,Y 

2634:8C 8F 28 113 STY SAVE SAVE YREG 

2637248 114 PHA 

2838:29 63 115 AND #583 ISOLATE BIT OFFSET OF OPCODE 
263A3A8 116 TAY 

283B:68 117 PLA 

283C:4A 118 ESR A 

203D:4A 119 CSR A DIVIDE BY 4 (BYTE OFFSET} 
“2@3ES AA 12@ TAX 

203F:BD 98 29 121 LDA OPTAB,X GET 4 OPCODES' LENGTHS 
2042:88 122. OPLOOP DEY 
. 2043:38 04 2649 123 BMI OPDONE SHIFT OUT THE 2 BIT LEN 
2045:4A 124 LSR A 

2046:4A 125 LSR A 

2647:D@ FO 2042 126 BNE OPLOOP 

2449:29 03 127 OPDONE AND #$83 ISOLATE LENGTH 

204B:FO 26 2073 «128 BEQ COPIED @ LENGTH OP (S$FF) SIGNALS END 
2@4D:AA 129 TAX 

204E:AC 8F 20 138 LbY SAVE RESTORE YREG 

2851:E@ 83 131 CPX #3 

2053:F8 8c 2061 132 BEQ RELOC RELOCATE ALL 3 BYTE OPS 
2055:C8 133 INY 

2856:CA 134 DEX 

2657:F8 D6 262F 135 BEQ COPY 1 BYTE OP? 

2659:B9 @@ 21 136 LOA TYPENT,Y NO, THAT LEAVES 2 BYTE OPS 
205C:91 48 137 STMSB STA (PTR) ,Y 

265E:C8 138 INY 

205F:00 CE 202F 139 BNE COPY CONTINUE COPYING 

2061: 141 * RELOCATE’ ABSOLUTE ADDRESSES IN INSTRUCTIONS 
2061:C8 143 RELOC INY 

2062:B9 88 21 144 LDA TYPENT,Y COPY LSB OF ADDR 

2065:91 48 145 STA (PTR) ,¥ 

2067:C8 146 INY 

2668:B9 G8 2) 147 LDA TYPENT,Y 

206B:C9 21 148 CMP #<TYPENT THIS ADDR WITHIN TYPENT? 
286D:D8 ED 20Ssc 149 BNE STMSB NO 

206F:A5 49 156 LDA PTR+1 YES, USE MSB OF NEW KOME 
2871:D@ E9 265C 151 BNE STMSB ALWAYS TAKEN 

2673: 153 * RESIDENT CODE HAS BEEN INSTALLED, WE CAN EXIT 
2873:4C 96 BE 155 COPIED, JMP BIENTRY OONE, EXIT 

2076: Li INSTALLATION DATA 

2076: 159 MSB ON 

2076:CE CF A@ D2 166 MSG ASC "NO ROOM FOR NEW COMMAND’ 


208D:87 8D 161 OFB $87,$8D 
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208F: 06 


26990; 
2690: 
2698: 
20968; 
2096: 
2096: 


2698:59 
2694:5A 
2698:5B 
269C:5A 
20A6:59 
20A4:5A 
20A8:59 
26AC:5A 
26B8:59 
206B4:5A 
26B8:6A 
20BC:5A 
26CO:5A 
26C4:5A 
26C8:5A 
26CC:5A 


2104:85 
21066:AD 
21869:85 
210B:AB 
216D:Bl 
210F:09 
2112:08 
2114:C8 
2115:C8 
2117:98 


2119; 
2119: 


2119:88 
211A:8C 
211D:A9 
211F:80 
2122:A9 
2124:8D 
2127:A9 
2129:8D 
212C:AD 
212F:AD 
2132:8D 
2135:AD 
2138:8D 
213B:18 
213C:6@ 


213D: 
213d: 


213D:38 
213E34C 


oe 


2106 


BE 


BE 


21 


2130 


216D 


SAVE DFB @ SAVE AREA FOR YREG 
* EACH BYTE CONTAINS THE LENGTHS OF 4 6542 OPCODES 
* FOR EXAMPLE, AT +@ IS A $59. 
* IN BINARY $59 = @1611961 OR 
Ld 61 @1 16 61 (1,1,2,1) 
* THESE ARE THE LENGTHS (IN REVERSED ORDER) FOR BR 
* ORA (N,X), AND TWO UNDEFINED OPCODES. 
OPTAB DFB $59,$69,$59,$7D OPCODE LENGTH TABLE 
DOFB $5A,$69,$5D,$7D 
DFB $5B,$6A,$59,S7F 
DFB $5A,$69,$50,$7D 
OFB $59,$69,$59,S7F 
OFB $5A,$69,$5D,$7D 
DFB $59,$69,$59,S7F 
DFB $5A,$69,$5D,$7D 
DFB $59,$6A,$55,$7F 
DFB $5A,$6A,$5D,$5D 
DFB $6A,$6A,$59,S7F 
DFB $5A,S$6A,$5D,$7F 
DFB $5A,$6A,$59,S7F 
DEB $5A,$69,$5D,$7D 
DFB $5A,$6A,$59,$7F 
DFB $5A,$69,$5D,$3D ONLY SFF GIVES @ LEN 
* NOW STARTS THE RESIDENT CODE WHICH IS MOVED TO HIGH 
* MEMORY, 
* TYPENT IS CALLED BY THE BI WHENEVER IT DOESN'T 
* RECOGNIZE A COMMAND. WE TAKE A LOOK AT IT SO SEE IF 
= IT MIGHT BE THE "TYPE" COMMAND. 
ORG TYPE+256 MUST BE PAGE ALIGNED 
TYPENT CLD 3; IDENTIFY TO BI 
LDA = VPATHL COPY COMMAND LINE PTR 
STA PTR 
LDA = VPATH1+1 
STA = PTR+#1 
LbY #1 
COMPR LDA (PTR) ,¥ COMPARE COMMAND STRING 
CMP NAME-1,Y TO "TYPE" 
BNE NOTIT NOT IT, VECTOR ON 
INY 
cPpy #4 
BCC COMPR CHECK ALL 4 CHARS 
* IT HAS BEEN. DETERMINED THAT THIS COMMAND IS MINE. 
* RETURN TO THE BI TO PARSE THE PATHNAME OPERAND 
DEY 
STY  XLEN STORE COMMAND LINE INDEX 
LDA #8 
STA  XCNUM COMMAND NUMBER @ (EXTERN) 
LDA #SD SLOT/DRIVE PERMITTED 
STA PBITS+1 
LDA #FN1 WE NEED PATHNAMEL] 
STA = PBITS 
WHERE LDA  TYPBAK <USED TO FIND TYPBAK> 
LDA  WHERE+1 TELL BI WHERE TO RETURN 
STA  XTADDR 
LDA WHERE+2 
STA  - XTADDR+1 
cLC 3; INDICATE COMMAND WAS FOUND 
RTS ; BACK TO BI FOR MORE PARSING 
* IF WE DON'T CLAIM A COMMAND, PASS IT THROUGH TO ANY 
7 OTHER EXTERNAL COMMAND HANDLERS 
NOTIT SEC 3} INDICATE COMMAND NOT FOUND 
NXTCOM JMP $8688 <OLD EXTCMD VECTOR> 
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2141:4C 


2144: 
2144; 


214434 
2146:8C 
21493A9 
214B:8D 
214E:3A9 
2150:29 
2153:B@ 
2155:AD 
2158:8D 
215B:80 


215E: 


215E:3A@ 
2166:8C 
2163:8C 
2166:C8 
2167:8C 
216A:C8 
216B:8C 
216E:A9 
2178328 
2173390 
2175:¢9 
2177:06 
2179:A9 
2178:208 
217E:A9 
2180:4C 


2183: 


2183:AG 
2185:B9 
2188:69 
218A:3208 
218D:AD 
2196:18 
2192:8D 
2195:C9 
2197:3F8 
2199:AD 
219C:10 
2196:8D 
21A1:C9 
21A3:F@ 
21A5:C8 
21A6:CC 
21A9:08 
21AB:F@ 


21AD: 
21A0354 
21B1:FF 


69 


59 
FF 


BE 


2141 


2183 


2141 


FD 


BE 


235 


237 


248 


TYPERR 


* 
* 


TYPBAK 


TYPLP 


TYQUIT 


* 


TYPPRT 
TYPPLP 


TYPWT 


TYPON 


NAME 


IMP 


ERROUT 


VECTOR TO BI ERROR EXIT 


ONCE THE COMMAND HAS BEEN PARSED, THE BI CALLS THE 
FOLLOWING CODE TO FINISH HANDLING TRE COMMAND 


Loy 
Sty 
LDA 
STA 
LDA 
JSR 
BCS 
LDA 
STA 
STA 


FILE IS 


LbY 
sty 
sty 
INY 
STY 
INY 
STY 
LDA 
JSR 
BCC 
cMpP 
BNE 
LOA 
JSR 
LDA 
IMP 


HIMEM+] 
OSYSBUF+) 
#0 
OSYSBUF 
#$C8 
GosYs 
TYPERR 
OREFNUM 
RWRFNUM 
CFRFNUM 


MSB OF BUFFER AREA 
COPY TO OPEN LIST 


MLI: OPEN 

OPEN THE FILE 
ERROR? 

COPY REF NUM 
TO READ LIST 
AND CLOSE LIST 


OPEN, READ 256 BYTES AT A TIME 


#6 
RWDATA 
RWCOUNT 


RWCOUNT+1 
RWDATA41 


256 BYTES AT A TIME 


TO $268 

MLI: READ 

READ 256 BYTES TO $208 
ALL WENT WELL 

EOF ERROR? 

NO, REAL ERROR 


PRINT A FINAL NEWLINE 
MLI: CLOSE 
EXIT THROUGH CLOSE 


COPY READ BUFFER TO SCREEN 


LDY 
LDA 
ORA 
JSR 
LOA 
BPL 
STA 
CMP 
BEQ 
LDA 
BPL 
STA 
CMP 
BEQ 
INY 
cpy 
BNE 
BEQ 


MSB 
ASC 
DFB 


#6 
$206,¥ 
#S$86 
cout 
KBD 
TYPON 
KBDSTB 
#883 
TYQUIT 
KBD 
TYPWT 
KBDSTB 
#$83 
TYQUIT 


RWTRANS 
TYPPLP 
TYPLP 


OFF 
‘TYPE’ 
SEF,SFF,SFF 


COPY BYTE BY BYTE 

MSB ON FOR COUT 

TO OUTPUT VECTOR 

CHECK FOR INTERVENTION 
NOTHING, CONTINUE 

CLEAR STROBE 

CONTROL-C? 

YES, EXIT NOW 

WAIT FOR A SECOND KEYPRESS 


CLEAR STROBE 

CONTROL-C? 

YES, ABORT 

7 ELSE, CONTINUE TYPING 
UNTIL BUFFER EMPTY 


THEN GO READ ANOTHER 


COMMAND NAME 
END OF PROGRAM FLAGS 
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DUMBTERM— DUMB TERMINAL PROGRAM 


DUMBTERM is an example of how to program under ProDOS 
using interrupts. DUMBTERM acts as a simple, line-at-a-time 
terminal emulation program which interfaces to a California 
Computer Systems CCS 7710 serial card. The same program can 
be written for an Apple Super Serial card (but interrupts are not 
as reliable for that card). The main portion of the program merely 
loops, checking the keyboard and the serial card for incoming 
data. If a keypress is found, it is sent out over the serial line. If 
--incoming serial data is found, it is displayed on the screen. 

The meat of the program lies within the communications 
subroutines in the last half of the listing. COMINT initializes the 
CCS card for interrupts after passing the address of its interrupt 
handler (COMIRQ) to ProDOS via the ALLOC_INTERRUPT 
MLI call. Each time an interrupt occurs, the COMIRQ handler is 
called by ProDOS and it examines the CCS status register to 
determine whether the interrupt was raised by the CCS card. If 
not, COMIRQ returns to ProDOS with the carry flag set to indicate 
that it is not claiming the interrupt. This gives other interrupt 
handlers a chance to service the interrupt. If the interrupt was 
generated by the CCS card and incoming data is available, a 
character is read and stored in a 256-byte circular buffer and 
COMIRQ exits to ProDOS. 

The buffer is called circular because a pair of index pointers are 
used (start of data, end of data) to mark the actual data within the 
buffer and these pointers may wrap at the end of the buffer back to 
its beginning. Thus, conceptually the buffer has no beginning or 
end. This means that the main program may be doing something 
else but the interrupt routine can buffer up to 256 characters 
coming in from the serial port before it will lose data. If the main 
part of the program was ever vigilant and constantly checked for 
incoming serial data, there would be no need for an interrupt exit. 
However, each time the COUT screen output subroutine is called, 
there is a potential that control will not return before the next 
character is available. This is because the Apple scrolls the screen 
by moving every line up a byte at a time, one by one. The process of 
scrolling a 40-column screen lasts over one character time at 1200 
baud (120 characters per second) on the serial port. Thus, without 
an interrupt exit, a character would be lost each time the screen is 
scrolled up one line. 
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Ideally this should be all there is to it. On an Apple IJ Plus, 
DUMBTERM works well under most circumstances and with 
most 80-column cards. Unfortunately this is not the case on an 
Apple Ile. Due to an error in programming the Apple IIe ROM, 
the entire process of scrolling the 40-column screen in PR#0 mode 
is disabled from interrupts! Thus the interrupt exit is useless in 
this mode. For 80-column scrolls, the ROM also disables interrupts 
while scrolling the bank switched text page, and the interrupt exit 
is again useless (at 1200 baud anyway). The only mode where the 
exit is reliable is the 40-column mode with PR#3 (control-Q). There 
are ways of avoiding these problems for 1200 baud. One is to 
change the window size (so that the monitor has less data to scroll). 
This is done by storing a new bottom line value at $23. In PR#0 40- 
column mode, this value should be $15. In 80-column mode, it must 
be $0E. Another solution would be to reproduce the scrolling code 
from the monitor into your own program and “sniff” for interrupts 
(i.e. enable for interrupts and disable again) more frequently than 
Apple does. It is also worth noting that some 80-column cards, such 
as the ALS Smarterm, “scroll” by moving a hardware “top of 
screen” pointer. No CPU time is required to scroll this way and 
terminal programs are much easier to write. 

DUMBTERM is also an example of a simple Interpreter or 
System Program. It sets up the stack register and ProDOS version 
fields in the System Global Page upon entry, and it exits upon 
sensing a control-C keypress using the MLI QUIT call. 


ere NEXT OBJECT FILE NAME IS DUMBTERM.S.@ 


PROGRAMMER: DON D WORTH 3/8/84 


2000: 2068 1 ORG $2680 
2089 3 TT RT RARE EERE ER AREER K ARERR RR 
2066: 4 * 2 
2000 5 * DUMBTERM: THIS PROGRAM ACTS AS A DUMB TERMINAL Gd 
2060 6 * THROUGH A CCS 771@ SERIAL CARD USING = 
2600 q * THE PRODOS INTERRUPT HANDLER FOR INPUT * 
2080 a. INTERRUPTS. THIS PROGRAM FOLLOWS THE RULES i 
20668 ad FOR A PRODOS INTERPRETER. 5 
2008 1e@ * sf 
20080 Jl * ASSUMPTIONS: CCS771@ CARD IN SLOT 1 . 
2068: Hai * 8 DATA BITS, 1 STOP, NO PARITY * 
2000: OG ad BAUD RATE SET BY DIP SWITCHES ON CARD >. 
2606: 14 * ~ 
2606; 15 * ENTRY POINT: $2660 * 
2600; 16 * * 
2000: 17 * * 
: ® * 
* * 


ITO TIE ORO UE IO RRO 6 ii i Rida Re 
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2068: 6987 21 BELL EQU $87 BELL CHARACTER 

2800: 96GD 22.CR EQU  $@D RETURN 

2008: @88D 23 RETURN EQU  $8D PRINTABLE RETURN 

2000: @GAG 24 SPACE EQU SAG BLANK 

2608: 26 * ZPAGE DEFINITIONS 

2006: 663C 28 ALL EQU $3C MONITOR POINTER 

2680: 8630 29 AlH EQU $30 

2880: 603 30 A2L EQU S3E MONITOR POINTER 

2006: OO3F 31 A2H EQU $3F 

20668: 33 * OTHER ADDRESSES 

2000: BF@@ 35 MLI EQU  SBFG8 PRODOS ENTRY POINT 

2008: BF98 36 MACHID EQU  _ SBF98 PRODOS MACHINE ID 

2096: BFFC 37 IBAKVER EQU  S$BFFC MLI VERSION WANTED 

2690: BFFD 38 IVERS EQU SBFFD MY VERSION 

2006: C@B6 = 39 _-KBD EQU $C BBG KEYBOARD STROBE 

2606: CG1@ 4 KBDRES EQU  $CO16 KEYBOARD RESET 

2608: FDED 41 COUT EQU  $FDED MONITOR OUTPUT SUBROUTINE 
2004: FD@C 42 RDKEY EQU- SFDEC MONITOR INPUT SUBROUTINE 
2608: FC58 43 HOME EQU  $FC58 MONITOR HOME 

2608: FB39 9 44.‘ TEXT EQU  SFB39 SET TEXT MODE 

2000: 46 * START OF DUMB TERMINAL EMULATOR 

200G:A2 FF 48 DTERM LDX  #SFF SET UP STACK POINTER * 
2602:9A 49 TXS 

2863:A9 66 58 LDA #0 

2095:8D FC BE 51 STA IBAKVER VERSION @ FOR EVERYBODY 
2008:8D FD BF $2 STA IVERS 

208B:2@ 62 208 53 JSR COMINT INITIALIZE SERIAL PORT 
206E:28 58 FC 54 JSR HOME CLEAR SCREEN 

2611:A9 G2 55 LDA = #$82 

2613:2C 98 BE 56 BIT MACHID 8G COLUMN CARD PRESENT? 
2816:F6 63 281B 57 BEQ BEGIN NO 

2618:28 88 C3 58 JSR $C380 INITIALIZE 8@ COLUMN CARD 
261B: 69 * 

2018: 61 * NOTE: NO NEED TO SET BIT MAP HERE SINCE NOT DOING 
201B: 62 * DYNAMIC MEMORY ALLOCATION. AND WE WILL LEAVE 
261B: 63 * THE POWERUP BYTE SO THAT RESET FORCES REBOOT. 
261B: 64 * 

201B: 281B 65 BEGIN EQU) * 

201B: 66 * 

201B: 67 * --- SPECIAL NOTE --- 

201B: 68 * 

261B: 69 * IF AN APPLE ][E IS USED, THERE MAY BE DATA 

201B: 78 * ERRORS AT 1284 BAUD WHEN SCROLLING. IF THIS 
201B: 71 * OCCURS, INSERT THESE INSTRUCTIONS AT THIS POINT: 
201B: 72 * 

2018: 73 * LDA #SGE SET WINDOW 14 LINES HIGH 
261B: 74 * STA $23 

281B: 75 * 

261B: 76 * (LDA #$15 IF YOU HAVE NO 8@ COL CARD IN YOUR J [E. 
261B: 77 * 

261B: 79 * MAIN TERMINAL LOOP 

2@1B:AD F4 20 81 LOOP LDA ERRORS. HAVE ANY ERRORS OCCURED? 
2G1E:F@ BA 202A 82 BEQ  NOERRS NO 

2628:A9 87 83 LDA #BELL YES, BEEP AT HIM 


2022:26 ED FD 84 JSR cout 
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2625:A9 
2827:8D 
202A:AD 
262D:18 
202F:29 
20321:C9 
2033:F0 
2035:AD 
2038:8D 
203B:20 


203E:28 
2041:F0 
2043:26 
2046:09 
2648:C9 
204A:FO 
284C:208 
204F:34C 


2852: 


2052:20 
2055:26 
2058:65 
2659:5B 
205B:04 
2950369 
2850: 88 
205F:06 
2069:06 


2862: 
2062: 
2062: 
2662: 
2862: 


2062: 
2062: 
2062: 


2062: 


2062:A9 
2664:8D 
2067:8D 
266A:20 
2060:408 
206E: FG 
2070:A9 
2672:8D 
2075:3A9 
2077:80 
207A:KE 
2070:09 
207F:8D 
2082766 


2083: 


2083:3AD 
2086: 30 
2088: 38 
2089:60 
208A; 48 
268B:29 
298D:FG@ 
208F:EE 
2092368 


ae 


oe 


28 
BF 


COSE 
COSE 
COOF 


20 
20 
BE 


ce 


ce 
ce 


ce 


ce 
208A 


2092 
26 


123 
124 
125 


127 


129 
136 
131 
132 
133 
134 
135 
136 
137 
138 
139 
146 
141 
142 


144 


146 
147 
148 
149 
158 
isl 
152 
153 
154 


LDA #8 AND CLEAR ERROR COUNTER 
STA ERRORS 
NOERRS LDA KBD FIRST TEST KEYBOARD 
BPL NOKEY NOTHING YET? 
AND #S7F 
CMP #3 CONTROL~C? 
BEQ EXIT 
LDA KBD RELOAD CHARACTER 
STA KBDRES CLEAR KEYBOARD 
JSR COMOUT SEND THE CHARACTER OUT 
NOKEY JSR COMTIN TEST FOR AVAILABLE INPUT 
BEQ LOOP NONE, CHECK KEYBOARD AGAIN 
JSR COMINP GET NEXT INPUT CHARACTER 
ORA #888 MSB ON FOR OUTPUT 
CMP = #S8A LINE FEED? 
BEQ LOOP YES, SKIP IT 
JSR COUT ELSE, PRINT IT 
JMP LOOP AND CONTINUE LOOP 
* IF CONTROL-C IS TYPED, EXIT 
EXIT JSR COMCLS CLOSE DOWN COMM LINE 
JSR MEI MLI: QUIT CALL 
OFB $65 
DW QPARMS 
QPARMS DEB 4 QUIT PARMLIST 
DEB OG 
Dw @ 
DFB 8 
pw a 
ERR REE KEE EERE RHEE EEAERAKEKEKEEKEAAARKRAERAKHKKEK 
* x 
* CCS 7716 COMMUNICATIONS SUBROUTINES « 
* x 
RRR REREKERERRKEAKAREAARAEKRHARETARaERKKRKEKERERKEKEKAHKEK 
cccom EQU  SCO9E CCS COMMAND REG 
ccsTs EQU  $CO9E CCS STATUS REG 
CCDTA EQU SCOOF CCS DATA REG 
* COMINT: INITIALIZE THE COMM LINE 
COMINT LDA #0 
STA CIRCS START CIRCULAR BUFFER PTRS 
STA CIRCE 
JSR MLE ALLOCATE INTERRUPT EXIT 
DFB $4@ 
DW APARMS 
LDA -#S$23 RESET ACIA 
STA CCCOM 
LDA #$15 8 BITS/1 STOP/NO PAR/NO INTS 
STA CCCOM 
Lox CCDTA THROW AWAY ANY GARBAGE 
ORA  -#$86 ENABLE INTERRUPTS 
STA CCCOM 
RTS 
* COMIRQ: INTERRUPT EXIT 
COMIRQ LDA ccsTSs CHECK STATUS 
BMI COMME INTERRUPT WAS FOR ME? 
SEC ; INDICATE NOT MY INTERRUPT 
RTS 
COMME PHA 
AND #$76 ANY ERRORS OCCURED? 
BEQ COMNE NO 
INC ERRORS YES, BUMP ERROR COUNT 
COMNE PLA 


A-40 
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2693:29 
2095:F8 
2097:AD 
2G9A:AE 
209D:3D 
26A0:E8 
20A1:8E 
20A4:EC 
20A7:D8 
20A9:EE 
2GAC:CE 
20AF:18 
26BG 369 


20B1: 
20B1: 


20B1:78 
2GB2:AE 
20BS3EC 
2@B8:58 
20B9:6G6 


20BA: 


26BA: 20 
20BD:F6 
20BF:78 
20CQ:AE 
28C3:BD 
20C6:E8 
20C7:8E 
20CA:58 
26CB:68 


2@CC: 


28CC:48 


28CD:AD 
28D6:29 


2802:FO 
2004:68 
2@05:8D 
2608:608 


20D9: 


26D9:5A9 
26DB:8D 
20DE:58 
26DF:A9 
26E1:8D 
26E4:26 
20E7:41 
26E68:FO 
20EA:A9 
20EC:8D 
20EF: 690 


20F@: 


26F0:62 
20F1:06 
26F2:83 


20F4:06 
20F5:00 
20F6:68 
20F7: 


FS 
F6 


Bl 
FB 


FS 
F7 


FBS 


G2 
Fo 


26 


20 
26 


28 


2a 
26 


28 


ce 


ce 


c@é 


26 
BF 


26 


2GAF 


20BA 


28CD 


6186 


155 
156 
157 
158 
1599 
168 
161 
162 
163 
164 
165 
166 
167 


169 
178 


172 
173 
174 
175 
176 


178 


186 
181 
182 
183 
i84 
185 
186 
187 
188 


196 


192 
193 
194 
195 
196 
197 
198 


2808 


202 
203 
204 
285 
266 
267 
208 
209 
210 
211 
212 


214 


216 
217 
218 


226 
221 
222 
223 


AND 
BEQ 
LDA 
LDX 
STA 
INX 
STX 
CPx 
BNE 
INC 
DEC 
CLAIM cLe 
RTS 


COMTIN: 


COMTIN SEI 
LDX 
CPX 
cLI 
RTS 


7 COMINP: 


COMINP JSR 
BEQ 
SEI 
LDX 
LDA 
INX 
STX 
CLi 
RTS 


+ COMOUT: 


comouT PHA 
COMOL LDA 
AND 
BEQ 
COMOIT PLA 
STA 
RTS 


* COMCLS: 


COMCLS LDA 
STA 
CLI 
LDA 
STA 
JSR 
DFB 
Ow 
LDA 
STA 
RTS 


. DATA 


APARMS DFB 
DFB 
DW 


ERRORS DFB 
CirCcS DFB 
CIRCE DFB 
circ DS 


#$01 
CLAIM 
CCDTA 
CIRCE 
CIRC,X 


CIRCE 
CIRCS 
CLAIM 
ERRORS 
CIRCE 


CHECK FOR INCOMING DATA 
NONE, IGNORE OTHER INTERUPTS 
GET INCOMING BYTE 


STORE IT AT END OF BUFFER 


UPDATE END POINT 

WRAPPED BACK TO START? 
NO, DID NOT OVERRUN 
OVERRUN ERROR, BUMP COUNT 
BACK UP END POINT 

; CLAIM THE INTERRUPT 


TEST FOR AVAILABLE INPUT 
IF NEQ, DATA IS AVAILABLE 


CIRCS 
CIRCE 


WAIT FOR NEXT 


COMTIN 
COMINP 


CIRCS 
CERC,X 


CIRCS 


OUTPUT A BYTE 


CCSTS 
#S82 
COMOL 


CCDTA 


; DISABLE FROM INTERRUPTS 
CHECK CIRCULAR BUFFER 

SEE IF ITS EMPTY 

; REENABLE 


INPUT, RETURN IN AREG 

TEST STATUS 

NOTHING YET? 

; DISABLE TO MESS WITH CIRC 
GET INPUT CHARACTER 

BUMP START POINTER FORWARD 
; REENABLE POR INTERRUPTS 


FROM AREG 


CHECK STATUS 
ISOLATE TX BUFFER BIT 
NOT READY YET 


SEND BYTE 


CLOSE COMM PORT 


#$23 
CCCOM 


#1 
APARMS 
MLI 


STOP INTERRUPTS/DTR OFF 
7 JUST FOR SAFETY SAKE 
CHANGE PARMLIST 


DEALLOC_INTERRUPT 


LEAVE THINGS AS I FOUND THEM 


ALLOC_INTERRUPT PARMS 


ERROR STATISTICS 
START OF DATA IN CIRC 
END OF DATA IN CIRC 
CIRCULAR INPUT BUFFER 
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DISKETTE PROTECTION SCHEMES 


Protected software, that software which is modified in some 
way to prevent it from being copied or duplicated, has existed 
since very early in the history of the Apple II. This was even true 
of tape based software before disk drives were widely used. It is 
not known who protected the first piece of Apple software, but it 
has become a widespread practice. So has the practice of copying 
or breaking protected software. It should be pointed out that the 
following discussion will not take sides in the sometimes 
controversial subject of software protection. Rather, it will 
provide an informative look at the methods used to protect 
software and how those methods have been circumvented. This 
seems appropriate since almost all protection schemes now 
involve a modified or customized disk operating system. 

At this time, ProDOS is still relatively new and it is unclear if it 
will influence the current practice of protecting software. In thata 
ProDOS disk is identical to earlier operating systems (DOS 3.3) at 
a byte level, it is certainly possible and probable that protection 
will exist. However, since ProDOS can and will support other 
storage devices (i.e. hard disks etc.), and with the current trend in 
sharing data between different applications, additional challenges 
exist for software developers. It is possible that the percentage of 
protected software may decrease somewhat with the introduction. 
of ProDOS. The following discussion will deal with software. 
protection in general on the Apple II family of computers. 
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A BRIEF HISTORY OF APPLE SOFTWARE PROTECTION 


The first protected software was tape based and appeared in the 
latter part of 1978, and protected disks followed shortly thereafter. 
Early protection schemes often were quite effective as there was 
relatively little technical information available. Almost any 
modification that rendered the normal means of copying useless 
was sufficient in most cases—most schemes did in fact consist of 
relatively minor changes to the normal format of data. Individuals 
were able to discover and disable these protection methods on a 
program by program basis, with little or no thought given to some 
automated means of reproducing protected software. 

It was not until perhaps a year later, in late 1979, thata 
significant event occurred in disk protection. An extremely 
popular product was introduced that employed a considerably 
improved protection method. This marked the beginning of an 
escalating battle between those protecting software and those 
trying to copy it. The protection methods used became more and 
more complex and involved, increasing time and expense for 
developers to create. The copiers also were increasing their efforts. 
Programs appeared that were designed to copy particular 
software products—a major development in that it defeated a 
great number of different schemes with a single basic technique. 
These programs are referred to as nibble copiers and were 
introduced in early 1981. 

Throughout this process, it is clear that both sides made use of 
the work of their counterparts. Protection schemes started to 
reflect a working knowledge of breaking techniques, and were 
often designed to circumvent a particular method or copier. The 
people breaking protection methods were also studying the various 
methods employed to stop them and producing increasingly 
effective tools. This produced a kind of ebb and flow seen in many 
competitive areas where each side gains a temporary advantage 
only to see it lost. Nibble copiers have had numerous revisions to 
cope with advancements in protection methods. 

Another significant milestone was the introduction ofa 
hardware card that could copy software from the Apple’s 
memory, thus bypassing most existing protection methods. While 
it is hard to single out advancements in protection methods, the 
mere presence of the numerous copy programs, hardware devices, 
bulletin boards, classes, and magazines aimed at defeating 
protection methods indicates the constant advancement of 
protection. Also, the fact that software developers continue to 
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protect software in the face of escalating costs indicates protection 
is still cost effective. 

The cycle will no doubt continue. As new sophisticated schemes 
are developed, they will be broken by equally sophisticated 
schemes. 


PROTECTION METHODS 


It seems reasonable at this time to say that it is impossible to 
protect a program on disk in such a way that it can’t be broken. 
This is, in large part, due to the nature of the Apple computer and 
its disk drive. It is an extremely well documented machine, with 
numerous publications available on both hardware and software 
functions. It is indeed difficult to hide anything (necessary in 
protecting software) from anyone who is willing to invest sufficient 
time to find it. 

Most disk protection methods fall into two different types of 
schemes. The first involves format alterations, altering some 
portion of the disk from its normal format (Chapter 3 and 
APPENDIX C provide descriptions of the normal format). The 
second involves creating an identifiable mark or signature that 
can be used to verify the disk. 
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GOPY PROTECTION: 
THE STRANGEST GAME. OF ALL 


B-4. Beneath Apple. ProDOS 


FORMAT ALTERATION 

A great number of ways exist to alter the format of normal data. 
They range from a single byte changed to an entirely different 
format. A special case is changing the location of data, and not 
necessarily the structure of the data itself. An early example of 
this was moving the directory information from its normal location 
to a different track altogether. Later, tracks themselves were 
moved when “half” tracks became popular (but data must be a full 
track apart from other data, a restriction imposed by hardware). 
Some disks now even use quarter tracks. Although these methods 
were effective for a while, most nibble copiers are equipped to 
handle them. 

A more elaborate technique used is known as spiral tracks. 
Data is staggered on alternating half tracks producing, as its name 
indicates, a spiral of sorts. Each half track contains approximately 
one third of a track of data. The actual amount will vary in 
different protection schemes. Note that no data is within one full 
track from any other data. If the relationship of the different 
segments is critical, this method of protection can be quite difficult 
to deal with. Several copy programs are capable of handling this, 
but may require parameters and additional time to reproduce a 
disk protected in this manner. 

As with location changes, format changes range from simple to 
complex. Almost all early changes were merely minor 
modifications to existing operating systems. The most common 
change was a change to the code that would read and write the 
Address Field. This was reasonable because the Address Field is 
never rewritten, and the only special code required was the code to 
read the modified Address Field. 

The Address Field normally starts with the bytes $D5/$A A/$96. 
If any of these bytes were changed, a standard operating system 
would not be able to locate that particular Address Field, causing 
an error. After the Address Field comes the address information 
itself (volume, track, sector, and checksum). Some common 
techniques include changing the order of this information, 
doubling the sector numbers, or altering the checksum with some 
constant. Any of the above would cause an error on a standard 
operating system. The Address Field ends with two closing bytes 
($DE/$AA), which can be changed or switched also. Similar kinds 
of changes can be made to the Data Field. These techniques 
worked well until automated programs appeared. 
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The first automated programs were good but generally made the 
assumption that the data portions had been modified and that the 
various gaps between the data portions were normal. This 
prompted modification of the gaps and eventually a radically 
different format in an attempt to circumvent the copy programs. 
These formats generally involved either different numbers of 
otherwise normal sectors on a track, or special sectors with 
Address and Data Fields combined. As with other advancements, 
this worked well for a time, but current nibble copiers make as few 
assumptions about the data format as possible and can generally 
deal with such techniques. 


SIGNATURE 


The earliest example of a signature was probably an unused 
track (track 3 was commonly “un” used). The software verifies the 
signature by trying to read a sector on the unused track. If an error 
occurred, the signature was verified. As simple as this seems now, 
it was reasonably effective. While this is a fairly obvious example 
of a signature, later methods were much more difficult to detect. 
In fact, most signatures have been uncovered by finding and 
examining the code that verified it. Once a method was known, an 
algorithm could be developed to deal with it. 

There are three common signatures used currently in protecting 
disks. The first to appear involves counting the number of bytes on 
a given track. This is commonly known as nibble counting. The 
reasoning was that no two drives spin at precisely the same speed, 
and therefore would not reproduce a track precisely. While this is 
in fact true, a number of programs now provide the means to 
reproduce this type of signature. 

Next to arrive was a method that was dependent on the 
positional relationship between different portions of the disk. This 
is commonly known as synchronized tracks. It generally involves 
reading a specific sector, then moving the disk arm to another 
track (often with nonstandard timing), and finding a particular 
sector first. The angle between the two sectors is arbitrary, but 
will always provide just enough time to move the arm and allow for 
any settling time needed. This relationship between tracks would 
not normally be maintained when copying the disk, and the 
signature would thus be removed. This also is provided for in many 
current copy programs, sometimes requiring parameters for a 
particular disk. , 
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The fina] method involves writing extra zero bits at given 
locations on a disk. These can be thought of as special sync bytes. 
When the disk is read, these extra bits are normally discarded. 
Figure B.1 shows two different bit patterns that produce the same 
data when read. A special routine looks for the extra bits and thus 
verifies the signature. There exist some variations to this method 
which have proved quite difficult for “nibble” copy programs to 
handle. Parameters were generally required, but recent 
advancements in nibble copiers appear to be able to locate and 
reproduce these extra bits. 

We have dealt primarily with disk protection schemes and 
nibble copiers, but several other methods of protection exist. These 
are protection methods which do not allow a program to be taken 
out of memory and patched to disable the protection scheme. It is 
worth mentioning that copies produced by a nibble copier are 
themselves protected, but software broken in some other way may 
be copied by normal means. 


14111111 —> FF 1111111100-——> FF 


Figure B.1. Comparison of a Normal FF Byte and a Special Sync 
Byte 


MEMORY PROTECTION 


It has long been realized that software is vulnerable as it is being 
loaded into memory, and when it resides entirely in memory. This 
has prompted a number of techniques, the earliest of which 
involved reset protection. When the Reset key was pressed (on 
early Apples), the software could be interrupted and was then 
resident in memory. Several memory locations were altered 
during a reset, and many programs were dependent on the values 
contained in those locations. The later Apple computers provide 
some measure of protection in that they make it much harder to 
interrupt software programs. The hardware boards designed to 
copy software from memory have made memory protection very 
difficult. The boards generate a Non-Maskable Interrupt and pass 
control to on-board software. It is not possible to prevent this 
interrupt from software. About the only defense is simply to never 
have the entire program in memory at one time. This is often 
inconvenient but may be the only effective defense. 
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CODE PROTECTION 


Hiding the code that reads the unusual disk format or checks 
for a particular signature has become increasingly popular. Early 
schemes rarely tried to hide anything because there were few 
people who knew where to look or even what to look for. But it is 
clear now that most of the advancements in nibble copiers resulted 
from the examination of the actual code that provided the 
protection. Signature schemes would have been effective much 
longer if it had been possible to hide the code that verified them. 
While it is impossible to prevent the code from being found, it can 
be made more difficult. The general method used is some sort of 
encryption of the code. It is decrypted just before execution, and 
either encrypted again or destroyed just after execution. 


THE IDEAL PROTECTION SCHEME 


There are thousands of programs available for the Apple II 
family of machines, and it is safe to say that they all have been 
copied despite a vast array of protection schemes. It seems 
reasonable to assume that this fact will not change. Nevertheless, 
it may be possible to devise a reasonably effective method. It would 
have to address the three primary ways that software is broken— 
nibble copiers, hardware boards that copy memory, and what we 
call the “front door” method. 


NIBBLE COPIERS 


Nibble copy programs have an advantage of sorts in that they 
need only respond to existing protection methods. This clearly 
requires considerable skill but not necessarily creativity. In 
fairness though, it should be noted that at least one of the nibble 
copiers has included capabilities that may effectively deal with yet 
to be created protection schemes. The best that one should hope for 
is a protection method that requires parameters to be input by the 
user of the copier. If the method could be varied so that each 
variation required a different set of parameters, it would be con- 
sidered a victory. 
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HARDWARE BOARDS 


It is not possible through software to detect the presence of these 
boards, nor prevent them from saving an image of memory onto a 
disk. For this reason, they are particularly effective with 
programs that are totally loaded into memory and require no 
additional disk accesses. The only good defense is to never have the 
entire program in memory at one time. While this could create 
some difficulties such as decreased performance for particular 
programs, it is nevertheless necessary for single program 
products. Modular software requiring constant disk access may 
already provide sufficient protection. 


FRONT DOOR METHOD 

The process by which a disk is loaded into memory is well 
defined for normal disks. Certain facts remain true of protected 
disks regardless of the method employed. First the disk must 
contain at least one sector (Track 0, Sector 0) which can be read by 
the program in the PROM on the disk controller card. Second the 
code that reads the protected disk must be on the disk. This means 
that it is possible to trace the boot process by disassembling the 
code involved in each step of that process. While this can be a 
formidable task, it is nevertheless theoretically possible to break 
all protection schemes with this method. The main defense against 
use of this method is to make it require a great deal of time to 
accomplish. This could primarily be done in several ways. 

One way is to write the code in separate modules or layers. 
Each layer typically decodes the next layer and recodes the 
previous layer. It is also vital to verify critical layers to ensure 
they have not been patched. A second way is to use an interpreted 
language which introduces an additional level of obscurity and a 
considerable amount of additional code. Neither of these can be 
entirely effective, but are important nevertheless. 


APPENDIX © 


NIBBLIZING 


This appendix covers in great detail the encoding of data 
(nibblizing) on the Disk IT family of drives (Disk II, Ile, and IIe). 
Some of this discussion may relate in a general way to encoding 
techniques on other computers made by Apple. But the details 
relate specifically to ProDOS and its device driver for a Disk II (or 
equivalent). ; 

Before starting an explanation of encoding, it is fair to ask why 
data must be encoded at all? It seems reasonable that the data 
could simply be written to the disk as it is without any encoding. 
The reason this can’t be done involves the hardware itself. Apple’s 
design of the original Disk II was innovative and used a unique 
method of recording the data. While this allowed Apple to produce 
an excellent product, it did require some additional work to be 
done in software. It is not possible to read all 256 possible byte 
values from a diskette. This was clearly not an insurmountable 
problem, but it did require that the data stored on the disk be 
restricted to bytes with certain characteristics. 


ENCODING TECHNIQUES 


Three different techniques have been used. The first one, which 
is currently used in Address Fields,:involves writing a data byte as 
two disk bytes, one containing the odd bits, and the other 
containing the even bits. This method is often referred to as “4 and 
4” encoding, depicting the fact that an 8-bit byte is split into two 4- 
bit pieces. It requires two disk bytes for each byte of data, thus 512 
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disk bytes would be needed for each 256-byte sector of data. Had 
this technique been used for sector data, no more than 10 sectors 
would have fit on a track. This amounts to about 88K of data per 
diskette, typical for 5 1/4 inch single sided, single density drives. 

Fortunately, other techniques for writing data to diskettes were 
devised that allowed more sectors per track. The earliest technique 
involved 13 sectors per track. This initial method involved a “5 and 
3” split of the data bits, versus the “4 and 4” mentioned earlier. 
Each byte written to the disk contains five valid bits rather than 
four. This required 410 disk bytes to store a 256-byte sector. 
Currently, of course, ProDOS features 16 sectors per track and 
uses a “6 and 2” split of data bits thereby requiring 342 disk bytes 
per 256-byte sector. This allows 140K of data per diskette. 

The two different encoding techniques (“4 and 4” and “6 and 2”) 
will now be covered in some detail. The hardware (in order to 
insure the integrity of the data) imposes a number of restrictions 
upon how data can be stored and retrieved. It requires that a disk 
byte have the high bit set (the first bit is a “1”), and in addition, it 
can have no more than two consecutive zero bits. Further, each 
byte can have at most one pair of consecutive zero bits. 


“4 AND 4” ENCODING 


The odd-even “4 and 4” technique meets these requirements— 
each data byte is represented as two bytes, one containing the even 
data bits and the other the odd data bits, (shifted one bit right). 
Figure C.1 illustrates this transformation. It should be noted that 
the unused bits are all set to “1” to guarantee meeting the two 
requirements. 


1D71Ds1D31D: 
DATA BYTE D7DeDsD4D3D2D:Do —<— 
1061D41D21Do 


FigureC.4 “4 and 4” Encoding Technique 


No matter what value the original data byte has, this technique 
insures that the high bit is set and that there cannot be two 
consecutive zero bits. The “4 and 4” technique is used to store the 
information (volume, track, sector, checksum) contained in the 
Address Field. It is quite easy to decode the data, since the byte 
with the odd bits is simply shifted left and logically AN Ded with 
the byte containing the even bits. This is illustrated in Figure C.2. 
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D7 1Ds10D3 10D: 1 (shifted left) 
AND 1 De1Da1 De 1 Do 


D7DeDsD4D3D2D:Do 


FigureC.2. “4 and 4” Decoding Technique 


It is important that the least significant bit is a 1 when the odd- 
bits byte is left shifted. The entire operation is carried out in the 
device driver for the Disk II. 


“6 AND 2” ENCODING 


The major difficulty with the above technique is that it takes up 
a lot of room on the track. Since each disk byte actually contains 
only four bits of real data, half the bits are wasted. To overcome 
this deficiency, the “6 and 2” encoding technique was developed. It 
is so named because, instead of splitting the bytes in half as in the 
“4 and 4” technique, they are split “6 and 2”. The two bits split off 
from each byte are grouped together to form additional 6-bit bytes. 
(They are stored in an area called the Auxiliary Data Buffer.) This 
means that only two bits are lost in each disk byte. The 6-bit bytes 
used take the form XXXXXXOO and have values from $00 to $FC, 
each being a multiple of four, for a total of 64 different values. 
Figure C.3 shows the 6-bit bytes. 


LOW ORDER 
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HIGH ORDER 
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FigureC.3 Valid 6-Bit Bytes 
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It was necessary to map these 64 6-bit bytes into disk bytes so 
that they can be stored on the disk. However, there are 72 different 
bytes ranging in value from $95 up to $F F that meet the 
requirements for valid disk bytes (i.e. the high bit set and one pair 
of consecutive zero bits at most). After removing the two reserved 
bytes, $AA and $D5, 70 disk bytes remain, and only 64 are needed. 
An additional requirement was introduced to force the mapping to 
be one to one, namely, that there must be at least two adjacent bits 
set, excluding bit 7. This produces exactly 64 valid disk bytes. A 
table of valid (and invalid) disk bytes is presented in Figure C.4. 
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HIGH NIBBLE 
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VALID “DISK” BYTES 

RESERVED BYTES 

INVALID—Three or More Consecutive Zero Bits 
INVALID—Two Pairs of Consecutive Zero Bits 
INVALID—Lacks Two Consecutive One Bits 
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Figure C4 Valid “Disk Bytes” 


The process of converting 8-bit data bytes to disk bytes is a fairly 
involved process. It has three separate components, two of which 
we have already mentioned. We will now detail the entire 
operation required to convert 256 bytes of data into data suitable 
for diskette storage. An overview of the process is diagrammed in 
Figure C.5. 
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Figure C.5a_ Writing to the Diskette 
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FigureC.5b Reading from the Diskette 








THE ENCODING PROCESS 


First, the 256 bytes that will make up a sector must be 
converted to 342 6-bit bytes. The number 342 results from finding 
the total number of bits (256 x 8 = 2048) and dividing by the 
number of bits per byte (2048 / 6 = 341.33). Four of the bits are not 
used. This operation is done by the “prenibble” routine in the Disk 
II device driver. The code that performs this operation is fairly 
involved, as it requires a good deal of bit rearrangement. The 
results of the operation can however be easily illustrated. Figure 
C.6 shows how the Auxiliary Data Buffer is formed. The 256-byte 
User Data Page (containing 8-bit bytes), is passed to the Disk IT 
device driver by ProDOS. Two bits are taken from each byte and 
put into the Auxiliary Data Buffer. The bits are rearranged 
slightly during this process. The two bits from each byte are 
reversed and the order in which they are stored in the Auxiliary 
Data Buffer is also reversed. The way in which these bits are 
rearranged and then stored is arbitrary—it could have been done 
differently. The method chosen can be executed rapidly witha 
small amount of code. The 256-byte User Data Page is in fact 
unchanged as the bits are copied rather than removed, these bits 
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DATA 
PAGE 


BIT POSITIONS 
76543210 


+00 






+55 
+56 
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BUFFER 


Figure C.6a_ Forming the Auxiliary Data Buffer 
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USER 
DATA 
PAGE 






+00 
AUXILIARY 


DATA 
BUFFER 


Figure C.6b Forming One Byte of the Auxiliary Data Buffer 


are ignored (stripped out) when the data is written to the disk. This 
double usage of the User Data Page eliminates the need for an 
additional buffer. The Auxiliary Data Buffer contains four areas, 
one unused and the other three containing segments of the last two 
bits of the User buffer as is graphically illustrated. 

The result of the first step is 342 6-bit bytes. The next step is that 
of creating a simple checksum that will be used to verify the 
integrity of the data. Like the Address Field, it also involves 
exclusive-ORing the information, but, due to time constraints 
during reading bytes, it is implemented differently. The entire 
block of data is exclusive-ORed with itself offset by one byte. This 
adds one byte, bringing the block of data to 343 bytes. This process 
is reversible and, while it cannot aid in recovering damaged data, 
it does provide a reasonable check on whether the data has been 
read correctly. The operation of exclusive-ORing the data block 
with itself is carried out a pair of bytes at a time. This enables the 
process to be carried out on the fly, that is, while the data is being 
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* Last data byte is used as checksum. 


Figure C.7 Writing from Buffers to Disk 


read or written. This step and the next are actually done together 
and are depicted in Figure C.7. 
The last step is to translate these 343 6-bit bytes to 8-bit disk 
bytes. This operation is performed using a data table in the Disk II 
device driver. Figure C.8 shows the mapping of 6-bit bytes to disk 
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FigureC.8 Relationship of 6-Bit Bytes fo Disk Bytes 
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bytes in greater detail. Three bytes are highlighted to graphically 
show how the translation is made. We see for example the $00 
becomes $96, $8C becomes $D3, and $FC becomes $FF. 


00 <-> 96 40<->B4 80 <>D6 CO<>ED 
04<>97 44<>B5 84<>D7 C4<>EE- 
08 <-> 9A 48 <-> B6 88 <-> D9 C8 <> EF 
0C <> 9B 4C<->B7 8C<->DA CC<>F2 
10<>9D 50 <-> B9 90 <>DB DO<->F3 
14<>9E 54<>BA 94<>DC D4<>F4 
18 <-> 9F 58 <-> BB 98 <>DD D8 <>F5 
10<>A6 5C<>BC 9C <>DE DC<>F6 
20 <> A7 60<> BD A0<> DF E0<>F7 
24 <> AB 64<>BE A4<>E5 E4<>F9 
28 <-> AC 68 <> BF A&8<>E6 E8 <-> FA 
2€<> AD 6C<> CB AC<->E7 EC<>FB 
30 <-> AE 70<>CD BO <-> E9 FO <>FC 
34<>AF 74<>CE B4<>EA F4<>FD 
38 <-> B2 78<> CF B8 <-> EB F8 <-> FE 
30<-> B3 70<>D3 BC<>EC FC <> FF 


FigureC.9 “6 and 2” Write Translate Table 


A tabular representation of the same mapping is shown in 
Figure C.9. It should be noted that this is in fact a two way 
mapping. When bytes are read from the disk they are converted 
back to 6-bit bytes using this same table. 

The reason for this transformation can be better understood by 
examining how the information is retrieved from the disk. The 
read routine must read a byte, transform it, and store it—all in 
under 32 cycles (the time taken to write a byte) or the information 
will be lost. By using the checksum computation to decode data, 
the transformation shown in Figure C.10 greatly facilitates the 
time constraint. As the data is being read from a sector, the 
accumulator contains the cumulative result of all previous bytes, 
exclusive-ORed together. The value of the accumulator after any 
exclusive-OR operation is the actual data byte for that point in the 
series. This process is diagrammed in Figure C.10. 


C-10 Beneath Apple ProDOS 


DISK BYTE 0 —— 


SFBSS 
piskByret ~——+ | [ AUXILIARY 
DATA 
DISKBYTE8S ~——» | 0 BUFFER 
DISK BYTE@s =——> | | es 
DISK BYTE87 —— | 2 
A 
N 
S 
L 
° USER 
i DATA 
PAGE 
: 
A 
B 
DISK BYTE 340. ——> |, 
DISK BYTE 341 ——+ | £ 
DISK BYTE 342. ——+ +FF 





* Last data byte is used as checksum. 


Figure C.40 Reading from Disk into the Buffers 


While containing specific information, the preceding discussion 
might still be viewed as somewhat of a theoretical presentation. 
The follow section will show each stage of the transformation that 
takes place as 256 bytes of data are prepared prior to being written 
to disk. The data chosen is real data that exists on the ProDOS 
System disk which wil] enable the reader to verify the following 
transformation. 
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STAGE 4 


The first stage consists of creating an auxiliary buffer thereby 
converting the 256 bytes of data to 342 bytes. Each byte in the 
auxiliary buffer is made up of bits from three different bytes of the 
original 256-byte data. Please note that the original 256 bytes are 
still unchanged. Figure C.11 illustrates the results of stage 1, 
highlighting several bytes to aid in following this process. 


AUX 1 


20 30 FB OC 68 
Din do oo—a-ac-4 00 BB FC OC 20 


00 00 80 00 30 BO CO 00 
00 40 20 CO CO 30 BO 40 
00 90 OC 2C 18 28 00 24 
10 00 08 04 80 04 OC 00 
8C 0C 00 FO CO 00 30 00 
00 80 80 2C CO CO OC 00 
40 20 90 A8 EO 80 40 80 
10 08 30 30 38 10 10 20 




















00 60 03 00 55 53 45 
1111102805353 26 44 49 53 4B 00 
06 00 00 06 00 00 00 
06 00 00 00 00 00 00 
00 C3 27 OD 09 00 06 
18 01 26 50 52 4F 44 
53 00 00 00 00 00 00 
00 00 FF 08 00 1F 00 
3C 00 21 AB 00 00 00 
21 00 20 21 A8 00 00 
00 2C [42] 41 53 49 43 

53 55) 53.54 45 4p 00 100M 
00 FF 27 00 15 00 00 

00 6F A7 00 00 00 00 

00 20 6F A7 00 00 02 

25 46 49 4C 45 52 00 

00 00 00 00 00 00 00 

FF 3C 00 33 06 00 64 

21 A8 00 00 00 00 21 

5 Ol 21 AB 00 00 02 00 

43 4F 4E 56 45 52 54 

(Q0} 00 00 00 00 00 00, = 
6F 00 2A 00 01 50 00770000 0Wo) 
61 A7 00 00 00 00 21 00 
20 61 A7 00 00 02 00 27 
53 54 41 52 54 55 50 00 
00 00 00 00 00 00 00 FC 
99 00 18 00 C9 2C 00 4F 
A7 00 00 00 00 21 01 08 
4F A7 00 00 02 00 25 4D 
4F 49 52 45 00 00 00 00 
00 00 00 00 00 00 Fc BI 













1011000} 


USER 1 USER 1 


Figure C.44 Example: Forming the Auxiliary Data Buffer 
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STAGE 2 


Beneath Appie ProDOS 


The second stage is to create a checksum by exclusive-ORing the 
entire 342-byte data block with. itself, offset by one byte. If it were 
not offset, the results would be undesirable (all zeroes). An 
additional byte is created in this process. While the last byte is in 
fact unchanged by the process and is independent of the preceding 
data, it serves as the checksum as seen in Figure C.12. 


AUX 1 


00000000 


90-——————————— 
(2oY 30 ic 30 £4 F8 oc 68 FOR 00100000 


24 
00 
00 
00 
10 
8c 
00 
40 
10 
14 


00 
40 
90 
00 
oc 
80 
20 
08 
00 


04 
80 
20 
oc 
08 
00 
80 
90 
30 
00 


00 


00: 


co 
2c 
04 
FO 
2c 
A8 
30 
84 


B8 FC 
30 BO 
co 30 
18 28 
80 04 
co 00 
co co 
EO 80 
38 


10.3} OC) 


USER t 


0c 20 00100000 


CO 00 BO 
BO 40 
00 24 
oc 00 
30 00 
oc 00 
40 80 


20 00001000 


EOR 
00000100 


£OR“10110001 
01001101 


USER 2 


AUX 2 


2C D4 iC F4 
04 B8 44 FO 
80 30 80 70 
EO 00 FO 80 
20 34 30 28 
oC 84 84 08 
FO 30 CO 30 
AC EC 00 CC 
38 48 60 CO 
00 08 28 00 








FigureC.42 Example: The Exclusive ORing Operation 
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STAGE 3 

The third and last stage is to translate the 343 6-bit bytes into 
disk bytes. This is done with a simple lookup table as shown in 
Figure C.18. Please note that during this step the last two bits are 
removed from all bytes before using the table. 


AUX 2 AUX 3 









WRITE 
10 AND FC = 10 TRANSLATE 
20 thy 2c 2c D4 1c F4 TABLE AD AD F4 A6 FD BE 
4C A8 88 04 BB 44 FO 2C 00<->96 B7 E6 D9 97 EB BS FC AD 
20 00 80 80 30 80 70 CO 04<>97 A7 96 D6 D6 AE D6 CD ED 


00 40 60 EO 00 FO 80 FO 08 <-> 9A 96 B4 BD F7 96 FC D6 FC 
40 90 9C 20 34 30 28 24 0C <-> 9B B4 DB DE A7 AF AE AC AB 
34 10 08 OC 84 84 08 OC 10 <>9D AF 9D 9A 9B D7 D7 9A 9B 
gc 80 OC FO 30 CO 30 30 DA D6 9B FC AE ED AE AE 
00 80 0G AC EC 00 CC OC 96 D6 96 E7 FB 96 F2 9B 
40 60 BO 38 48 60 CO CO B4 BD E9 B2 B6 BD ED ED 
90 18 38 00 08 28 00 30 DB 9F B2 96 9A AC 96 AE 


34 14 00 84 8C 04 AF 9E 96 D7 DA 97 


48 AND FC=48———__ 48<.>B6 
oc 00 03 03 FA AF 06\16 : 9B 96 96 96 FE E7 97 9E 
17 01 7D 6A OD 1A 18 [4B] 9E 96 D3 BF 9B 9F OF [Bé6] 


00 00 00 00 00 00 00 00 96 96 96 96 396 96 96 96 
00 00 00 00 00 00 00 00 96 96 96 96 396 96 96 96 
00 00 C3 E4 2A 04 09 06 96 96 ED F9 AC 97 9A 97 
06 18 19 27 76 02 1D OB 97 OF 9F AB CE 96 A6 9A 
OB 1C 53 60 00 00 00 00 9A A6 BO 96 96 96 96 96 
00 00 00 FF F7 08 IF IF 96 96 96 FF FD 9A A6 A6 
00 3C 3C 21 89 A8 00 00 96 B3 B3 A7 D9 E6 96 96 
00 21 21 20 01 89 A8 OG 96 A7 A7 A7 96 D9 E6 96 
02 02 2C 6E 03 12 1A OA 96 96 AD CB 96 9D 9F 9A 
6D 7D OA OA 07 11 08 4D CB D3 9A 9A 97 9D 9A B7 


. Oa eeeceeneeccccos 


orreeeOeSererrerrrerirt terry yy 





00 00 FF D8 27 15 15 00 BO <-> E9 96 96 FF F5 AB 9E 9E 96 
28 28 6F C8 A7 00 00 00 : AC AC CB EF E5 96 96 96 
21 21 20 4F C8 A7 00 02 : A7 A7 A7 B7 EF E5 96 96 
02 25 63 OF 05 09 17 52 : 96 AB BD 9B 97 9A 9E B9 
00 00 00 00 00 00 OC 00 : 96 96 96 96 96 96 96 96 
00 FF C3 3C 33 33 00 64 : 96 FF ED B3 AE AE 96 BE 
64 21 89 A8 00 00 00 21 FO <->FC BE A7 D9 E6 96 96 96 A7 
4F 6F 20 89 A8 00 02 02 F4 <-> FD B7 CB A7 D9 E6 96 96 96 
27 64 OC 01 18 13 17 06 FB <-> FE AB BE 9B 96 9F 9D 9E 97 
54 00 00 00 00 00 00 00 FC -.>FF BA 96 96 96 96 96 96 96 
FF 90 6F 2A 2A 01 51 50 FF DB CB AC AC 96 B9 BY 
61 C6 A7 00 00 00 21 21 BD EE E5 96 96 96 A7 A7 
20 41 C6 A7 00 02 02 27 A? B4 EE ES 96 96 96 AB 
74 07 15 13 06 01 05 50 CE 97 9E 9D 97 96 97 BO 
00 00 00 00 00 00 00 FC 96 96 96 96 96 96 96 FF 
65 99 18 18 C9 E5 2C 4F BE DD 9F 9F EF F9 AD B7 
E8 A7 00 00 00 21 20 09 FA ES 96 96 96 A7 A7 9A 
47 E8 A7 00 02 02 25 68 BS FA ES 96 96 96 AB BF 
02 06 1B 17 45 00 00 00 96 97 OF 9E BS 96 96 96 
00 00 00 00 00 00 Fc 4D 96 96 96 96 96 96 FF B7 
B1 AND FC = BO 
USER 2 USER 3 


Figure C.43 Example: Translation, the Final Step Before Writing 


APPENDIX D 


THE LOGIC STATE SEQUENCER 


Because there is such a close relationship between the disk 
hardware and the software that controls it, it seems appropriate to 
examine the firmware that directly responds to the software, that 
is, the Logic State Sequencer ROM. The code on this ROM actually 
controls the reading and writing of bits. While the information 
presented here should enable one to understand the process 
involved, it is nevertheless intended to be an overview and nota 
complete analysis. 

The Disk II family of drives uses a unique method of storing 
data on a disk. They use a method named GCR (Group Code 
Recording), unlike most current disk drives that use FM 
(Frequency Modulation) or MFM (Modified Frequency 
Modulation). This enables writing data bytes without the use of 
clock bits and thereby greatly increases the amount of data that 
can be stored on a given track. Apple has recently put the Disk 
Controller Card into a Custom Integrated Circuit. Versions of the 
Disk Drive Controller Unit (IWM—Integrated Woz/Wendell 
Machine) are now used on the Apple IIe and the Macintosh. The 
following discussion is based on the original controller card, but 
should apply functionally to the new chip as well. 
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LOGIC STATE SEQUENCER ROM 


The Logic State Sequencer is a 256-byte ROM on the disk 
controller card. The “program” stored there controls the data 
register, providing the actual means of reading and writing bits. 
The program on the ROM is unlike traditional software such as 
BASIC or machine language—it is a simple language with only six 
different functions or commands available. What makes it 
different and difficult to follow is how the flow of the program is 
determined. Traditional languages typically execute instructions 
in sequence until they encounter a control statement (such as 
GOTO or GOSUB) that indicates a new location. In the state 
machine, each byte is both a command (operating on the data 
register) and a control statement. What is unique is that the 
location of the next command to execute is only partially 
determined by the control statement. 

The program flow is additionally controlled by four external 
inputs, two provided by software and two provided by hardware. 
The software inputs are controlled by four memory locations, 
$CO8C through $CO8F. The locations are slot dependent (adding 
the slot number times 16 to the base address gives the appropriate 
address). Because of the nature of the state machine (timing), this 
is normally done with the X-register containing the offset (i.e. the 
slot number times 16). The two inputs provided by the hardware 
are the presence or absence of a read pulse and the status of the 
high bit of the data register. 

Each of the 256 bytes in the ROM is an available location that 
can be accessed with the appropriate control statements. Eight 
bits are needed to indicate all of the locations. Four of these bits are 
provided by each byte in the ROM and the remaining four bits are 
provided by the external inputs described earlier. The four bits in 
the control statement contained in each byte of the ROM indicate 
what will be called for the next “sequence,” and the four bits from 
the external inputs indicate what will be called for the next “state.” 
Figure D.1 depicts the ROM as a two dimensional array, with 
“sequence” and “state” each providing one dimension of the 
address of a given element. 
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‘FigureD.1 Sequencer ROM is Addressed by a 4-Bit Input (STATE) 
and a 4-Bit Control Statement (SEQUENCE) 


The 16 sequences are simply the hex numbers 0 through F, and 
are supplied by the high order nibble of each byte in the ROM. The 
low order nibble is the command number. For example, the byte 
“18” would execute command number 8 (no operation) and proceed 
to sequence 1. Each byte or instruction takes two cycles to execute, 
but the state machine is running twice as fast as the 6502, so only 
one 6502 cycle per state machine instruction is required. The six 
available commands that control the data register are listed in 
Table D.1. 


Table D1. Commands Which Control the Data Register. 


pee DATA REGISTER 
CODE|OPERATION BEFORE AFTER 


Clear XXXXXXXX* 00000000 
No operation ABCDEFGH |ABCDEFGH 


Shift left (bringing in a 0) ABCDEFGH |BCDEFGH0 

Shift right (WRITE protected)} ABCDEFGH }11111111 
(not WRITE protected) ABCDEFGH }OABCDEFG 

Load i 


Shift left (bringing ina 1) ABCDEFGH |{BCDEFGH1 





*XXXXXXXX and YYYYYYYY denote valid, but different bytes. 
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The logic of the state machine is difficult to follow even though 
relatively few operations are carried out on the data register. 
Figure D.2 graphically illustrates the logic. 


STATE 






























































0 
1 
2 
3 
4 
wi 5 
© ¢6 
=<— 
Lui 7 
=| 
cs 8 
Lu 
tT 9 
A 
B 
C Ef: 
D 
E 
F 
f CLR Ea) SR 
LC] Nop fH LD 
2 sLo @ su 


Figure D.2 Sequencer Commands 
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To make the task easier, the contents of the ROM will be 
analyzed in four parts, corresponding to the four software states. 
As mentioned above, the locations $CO8C—CO8F (plus the slot 
number times 16) partially control the state machine. These four 
locations control two switches, Q6 and Q7. If one of these addresses 
is accessed, the appropriate switch will be set as indicated in Table 


D.2. 
Table D2 State Switches 





The first state examined will be with switch Q6 on and Q7 off. 
This can be described as checking the write protect switch and 
initializing the state machine for writing. Table D.3 lists the 
contents of this portion of the state machine ROM. All the 
instructions are identical ($0A), each shifting the data register 
right (command A), bringing in the status of the write protect 
switch, and then going to sequence 0. This readies the hardware 
for writing since it is necessary to be in sequence 0 in order to write 
correctly. 
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TableD3 STATE: Q6 ON and Q7 OFF (Check Write Protect) 
HIGH BITCLEAR | HIGH BIT SET 
SEQUENCE 


NO NO 
PULSE} PULSE PULSE PULSE 








— © 


YiMOAWDpPoOwrtannrwy 


The next state examined is with switches Q6 and Q7 off (see 
Table D.4). This reads data from the disk, shifting in the appro- 
priate bits as a “Pulse” or “No Pulse” is detected by the hardware. 
Additionally, once the high bit of the data register is set, the data is 
retained until a read pulse is detected (0 bits or “No Pulses” are 
ignored). 

When switch Q7 is turned on (write mode), the presence or 
absence of a read pulse is ignored. For this reason, the ROM 
contains two identical 64-byte sections. Therefore, Table D.5 is 
presented in aslighly different format. Only two operations are 
carried out, loading the data register from the data bus, and 
shifting the data out one bit at a time, so that it can be written to 
the disk. Note that only sequences 2 and A carry out any action on 
the data register. 
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TableDA STATE: Q6 OFF and Q7 OFF (Read) 
lees HIGH BITCLEAR [| HIGH BIT SET 
SEQUENCE 
0 


[aauelSise leuael us 
PULSE|PULSE PULSE/ PULSE 
18 18 18 18 
2D 2D 38 38 













YMOOWPCHDIMP MAW 


GH EI 
HIGH BIT | HIGH BIT 


CLEAR 


SEQUENCE 
0 
1 
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This discussion should provide a general understanding of the 
Logic State Sequencer. For a comprehensive look at the disk 
hardware, an excellent source is Understanding the Apple II by 
Jim Sather, published by Quality Software. 


SEQUENCER EXAMPLE 


Table D.6 follows the state machine through a number of steps 
during the read process. It is assumed that a $D5 has just been 
read and is now in the data register. The state machine is 
executing the instruction at column 4 and sequence 2 of Table D.4 
and will continue to loop until a read pulse is detected. The 
instruction being executed is a $28 which performs a NOP (8 = No 
OPeration) and remains at sequence 2. In our example, the next 
byte to be read is an $AA (only the first 5 bits are shown in Table 
D.6). If the reader can understand this example, it should be 
possible to construct a similar table for any other read or write 
example. Note that the column number is controlled by the 
contents of the MSB of the data register and the presence or 
absence of a Read Pulse. 


SAY, HOW MUCH 
i$ DON WORTH? 
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TableD4 ASequencer Example 


IDATA READ| REFER TO TABLE D.4 INEXT 
STEPREGISTERIPULSECOLUMNSEQUENCHBYTESEQUENCE|ACTION**| 


WONANELWN Re 


NOK CORAL WNHOONMRDUNAERWNHTOHRUNDWPOWPwoMArAnNT ah WH OND 
WHE DTDOIMAMNAWNHODWAMDNAAEWNPRPSCORAUDPrPOWP YD OANIRMR NR WH ON 


4 
3 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
2 
2 
2 
1 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
1 
2 
2 
2 
2 





*Normal time to detect a read pulse (if one exists). 


**See Table D.1. Notation used here is borrowed from Understanding the Apple IT 
by Jim Sather. 


Notes 


APPENDIX E 


ProDOS, DOS AND SOS 


This appendix is intended to assist the reader who is moving 
programs and data between the ProDOS, DOS and SOS operating 
systems on Apple IIs and Apple IIIs. It is divided into two sections. 
One deals with the possible problems one might encounter moving 
from DOS 3.3 or DOS 3.2 to ProDOS with a particular emphasis on 
differences in BASIC programming on the two systems. The other 
section discusses the areas in which ProDOS and SOS are alike, 
and explains ways in which programs may be written which will 
run with minimal modification on either system. 


CONVERTING FROM DOS TO ProDOS 


The following is a list of potential problem areas when 
converting programs from DOS 3.3 or DOS 3.2 to ProDOS: 


1. Apple DOS allows 30 character file names with embedded 
special characters and blanks. ProDOS restricts file names to 
15 characters. The first must be a letter, and the rest may be 
letters, numbers or periods. No blanks or other special 
characters (other than period) may be in a ProDOS file name. 

2. The following DOS commands are not supported by ProDOS: 
MON, NOMON, MAXFILES, INT, FP, and INIT. MON and 
NOMON may be entered under ProDOS but they have no 
effect. 

8. Under ProDOS, the VERIFY command does not read through 
a file to check it for I/O errors. It only verifies the file’s 
existence. 
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4. 


10. 


11. 


12: 
13. 


14. 


Although the V keyword is syntactically permitted on ProDOS 
file commands, it is not supported. Programs which depend 
upon volume numbers must be changed to use volume names 
instead. 


. When the APPEND command is used on a “sparse” random 


file, it will position at the EOF position, not to the first “hole.” 


. CHAINing between BASIC programs is now supported with a 


command rather than by BRUNing a separate file. 


. The most significant bit of each byte is off in text files under 


ProDOS. Itis on in DOS text files. For example, a blank in 
DOS was stored as $A0. Under ProDOS, it is stored as $20. 


. Under DOS, many programs use statements of the form: 


PRINT CHR$(13);CHR$(4);“dos command to be executed” 
This will not work under ProDOS. The CHR$(4) must be the 
first item in the PRINT list. The CHR$(4) need not be the first 
thing on an output line, just the first thing ina PRINT 
statement. 


. DOS supports up to 16 simultaneously open files. ProDOS 


allows only 8. 

Less memory is available to BASIC programmers under 
ProDOS. With no files open, the amount of memory available 
is equivalent to that available under DOS with three open files. 
Each open file uses 1024 bytes under ProDOS. Under DOS, 
only 595 bytes are used per file. 

HIMEM should always be set to point to an even page 
boundary under ProDOS (a multiple of 256). 

ProDOS does not support Integer BASIC programs. 

The “HELLO” file name must be “STARTUP” on ProDOS. 
DOS allows the user to specify any name for the first file run. 
All low level assembly language interfaces are drastically 
different under ProDOS. The MLI must be called to perform 
disk accesses wherever the DOS File Manager and RWTS 
were used in a program. There is no exact equivalent to RWTS 
in ProDOS, so programs which access the disk by track and 
sector must be converted to use the READ and WRITE 
BLOCK MLI calls. 
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WRITING PROGRAMS FOR ProDOS AND SOS 


When writing programs which are to run on either ProDOS or 
SOS, consider the following: 


al, 


2, 


ProDOS and SOS volumes are identical in format. Either 
system can read the other’s diskettes. 

Block 1 ona ProDOS volume contains the SOS boot loader. 
This program is loaded instead of Block 0 when booted on an 
Apple III. It searches the directory for SOS.KERNEL and 
loads it instead of ProDOS. This means that a diskette can be 
constructed which will boot either ProDOS or SOS and run an 
application on either an Apple II or Apple III. 


. SOS allows up to 16 concurrently open files in BASIC. 


ProDOS allows only 8. 


. SOS uses different file types than ProDOS. A ProDOS CATA- 


LOG ona SOS diskette will produce hex codes for file type but 
this is normal. Table E.1 shows all ProDOS and SOS file types 
currently defined. 


. SOS memory management allows programs to allocate and 


free segments of memory by making system calls. Under 
ProDOS, programs must manage memory themselves by 
marking pages free or in use in the System Global Page. 


. SOS system calls are, for the most part, very similar to 


ProDOS MLI calls. The areas in which differences occur are: 
ProDOS filing calls apply only to block devices (disks), but 
SOS filing calls apply to all devices; GET_FILE_INFO under 
SOS gives the EOF position of a file, whereas ProDOS’s 
GET_FILE_INFO does not; SOS’s SET_MARK and 
SET_EOF positions may be given as relative to the current 
position, but ProDOS requires them to be absolute. 


. SOS interrupts are prioritized and managed by device drivers; 


however, ProDOS interrupts are polled sequentially and are 
managed by interrupt handlers installed using MLI calls. 
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Table E.4 ProDOS and SOS File Types 


HEX ProDOS 
TYPE |NAME |0OS MEANING 


both Typeless file 

both Bad blocks file 

SOS PASCAL code file 

SOS PASCAL text file 

both ASCII text file 

SOS PASCAL text file 

both Binary file 

SOS Font file 

SOS Graphics screen file 

SOS Business BASIC program file 

SOS Business BASIC data file 

SOS Word processor file 

SOS SOS system file 

SOS SOS reserved for future use 

both Directory file 

SOS RPS data file 

SOS RPS index file 

SOS SOS reserved for future use 

ProDOS | AppleWorks data base file 

ProDOS | AppleWorks word processing 
file 

ProDOS | AppleWorks spreadsheet file 

SOS SOS reserved for future use 

ProDOS | ProDOS reserved for future use 

ProDOS | ProDOS PASCAL file 

ProDOS | Added command file 

ProDOS | ProDOS user defined file types 

ProDOS | ProDOS reserved for future use 

ProDOS | Integer BASIC program file 

ProDOS | Integer BASIC variables file 

ProDOS | Applesoft BASIC program file 

ProDOS | Applesoft BASIC variables file 

ProDOS | EDASM relocatable object module 
file 

ProDOS | System file 





accesstime. The time required to 
locate and read or write data ona 
direct access storage device, such as 
a diskette drive. 


address. The numeric location ofa 
piece of data in memory, usually 
given as a hexadecimal number 
from $0000 to $F FFF (65,535 
decimal). A disk address is the 
location of a data sector, expressed 
in terms of its track and sector 
numbers. 


algorithm. <A sequence of steps 
which may be performed by a 
program or other process, which 
will produce a given result. 

alphanumeric. An alphabetic 
character (A-Z) or a numeric digit 
(0-9). In the past, the term referred 
to the class of all characters and 
digits. 

analog. Having a value which is 
continuous, such as a voltage or 
electrical resistance, as opposed to 
digital. 

AND. The logical process of 
determining whether two bits are 
both “1”s.0 AND 1 results in 0 
(false), 1 AND 1 results in 1 (true). 

arm. The portion of a disk drive 
which suspends the read/write head 
over the disk’s surface. The arm can 
be moved radially to allow access to 
different tracks. 


GLOSSARY 


ASCII (American Standard Code 
for Information 
Interchange). A hexadecimal to 
character conversion code 
assignment, such that the 256 
possible values of a single byte may 
each represent a alphabetic, 
numeric, special, or control 
character. ASCII is used when 
interfacing to peripherals, such as 
keyboards, printers, or video text 
displays. 


assembly language. Also known as 
machine language. The native 
programming language of the 
individual computer. Assembly 
language is oriented to the machine, 
and is not humanized, as is BASIC, 
PASCAL, or FORTRAN. An 
assembler is used to convert 
assembly language statements to an 
executable program. 


bank switched memory. Also 
called the language card. An 
additional 16K of memory which 
may only be accessed by “throwing” 
hardware switches to cause portions 
of the bank switched memory to 
temporarily replace the Monitor 
ROM memory in the machine. This 
is necessary because an Apple can 
only address 64K, and all addresses 
are already used with 48K, 4K of 
1/O and 12K of Monitor ROM. 
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base. The number system in use. 
Decimal is base 10, since each digit 
represents a power of 10 
(1,10,100,...). Hexadecimal is base 
16 (1,16,256....). Binary is base 2 
(1,2,4.8....). 

BI(BASIC Interpreter). Also 
called the BASIC System Program. 
The BI accepts user commands such 
as CATALOG and LOAD, and 
translates them into calls to the 
ProDOS Machine Language 
Interface (MLI). 


binary. A number system based 
upon powers of 2. Only the digits 0 
and 1 are used. For example, 101 in 
binary is 1 units digit, 0 twos, and 1 
fours, or 5 in decimal. 

bit cell. The space on a diskette 
which passes beneath the 
read/write head in a 4-microsecond 
interval. A bit cell contains a signal 
which represents the value of a 
single binary 0 or 1 (bit). 

bit map. A table where each binary 
bit represents the allocation of a 
unit of storage. ProDOS uses bit 
maps to keep track of memory use 
(System Bit Map) and of disk use 
(Volume Bit Map). 


bitslip marks. The epilogue ofa 
disk field, used to double check that 
the disk head is still in read syne 
and the sector has not been 
damaged. 


block. An arbitrary unit of disk 
space composed of two sectors or 512 
bytes. ProDOS reads and writes a 
block at a time to improve 
performance and to allow support 
for larger devices. 


BRK, Break. Anassembly 
language instruction which can be 
used to force an interrupt and 
immediate suspension of execution 
of a program. 


buffer. Anarea of memory used to 
temporarily hold data as it is being 
transferred to or from a peripheral, 
such as a disk drive. 

earry flag. A 6502 processor flag 
which indicates that a previous 
addition resulted in a carry. Also 


used as an error indicator by many 
system programs. 


eatalog. A directory of the filesona 
diskette. See directory. 


chain. A linked list of data elements. 
Data is chained if its elements need 
not be contiguous in storage and 
each element can be found from its 
predecessor via an address or block 
pointer. 


ehecksum/CRC. A method for 
verifying that data has not been 
damaged. When data is written, the 
sum of all its constituent bytes is 
stored with it. If, when the data is 
later read, its sum no longer 
matches the checksum, it has been 
damaged. 

clobbered. Damaged or destroyed. 
A clobbered sector is one which has 
been overwritten such that it is 
unrecoverable. 


coldstart. A restart of a program 
which reinitializes all of its 
parameters, usually erasing any 
work which was in progress at the 
time of the restart. 


contiguous. Physically next to. Two 
bytes are contiguous if they are 
adjoining each other in memory or 
on the disk. 

control block. A collection of data 
which is used by the operating 
system to manage resources. 
Examples of control blocks used by 
ProDOS are the Volume Control 
Block (VCB) or a Volume Directory 
Header. 


control charaeter. A special ASCII 
eode which is used to perform a 
unique function on a peripheral, but 
does not generate a printable 
character. Carriage return, line 
feed, form feed, and a bell are all 
control characters. 


controller card. A hardware circuit 
board which is plugged into an 
Apple connector which allows 
communication with a peripheral 
device, such as a disk or printer. A 
controller card usually contains a 
small driver program in ROM. 

CSWL. A vector in zero page, 
through which output data is passed 
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for display on the CRT or for 
printing. 
eycle. Thesmallest unit of time 

within the central processor of the 
computer. Each machine language 
instruction requires two or more 
cycles to complete. One cycle on the 
Apple is about one microsecond (one 
millionth of a second). 


datatype. The type of information 
stored in a byte. A byte might 
contain a printable ASCII 
character, binary numeric data, or a 
machine language instruction. 

decimal. A number system based 
upon powers of 10. Digits range 
from 0 to 9. 

deferred commands. ProDOS 
commands which may (or must) be 
invoked from within an executing 
BASIC program. OPEN, 
APPEND, READ, WRITE, and 
CLOSE are all examples of deferred 
commands. 


digital. Discrete values as opposed 
to continuous (analog) values. Only 
digital values may be stored ina 
computer. Analog measurements 
from the real world, such asa 
voltage or the level of light outside, 
must be converted into a numerical 
value which, of necessity, must be 
“rounded off” to a discrete value. 


direct access. Peripheral storage 
allowing rapid access of any piece of 
data, regardless of its placement on 
the medium. Magnetic tape is 
generally not considered direct 
access, since the entire tape must be 
read to locate the last byte. A 
diskette is direct access, since the 
arm may be rapidly moved to any 
track and sector. 

directory. A catalog of files stored 
on a diskette. The directory must 
contain each file’s name and its 
location on the disk as well as other 
information regarding the type of 
data stored there. In ProDOS, a 
directory is a file in itself and one 
directory can describe other, 
subdirectories. 

-disk initialization. The process 
which places track formatting 


information, including sectors and 
gaps, ona blank diskette. During 
diskette initialization, the ProDOS 
FILER also places a copy of the boot 
loader in Block 0 and creates an 
empty Volume Directory in Blocks 2 
through 5. The Volume Bit Map is 
also initialized in Block 6. 


displacement. The distance from 
the beginning of a block of data toa 
particular byte or field. 
Displacements are usually given 
beginning with 0, for the first byte, 
1 for the second, etc. Also known as 
an offset. 


DOS. Alsocalled DOS 3.2 and DOS 
3.3. An earlier disk operating 
system for the Apple, DOS was 
designed to support BASIC 
programming using the Disk II 
drive only. When hard disks became 
available, Apple introduced 
ProDOS. 


driver. A program which provides 
an input stream to another program 
or an output device. A printer 
driver accepts input from a user 
program in the form of lines to be 
printed, and sends them to the 
printer. 

dump. Anunformatted or partially 
formatted listing of the contents of 
memory or a diskette in 
hexadecimal. Used for diagnostic 
purposes. 


encode. To translate data from one 
form to another for any of a number 
of reasons. In ProDOS, data is 
encoded from 8-bit bytes to 6-bit 
bytes for storage. 

entry point(EPA). Theentry point 
address is the location within a 
program where execution is to start. 
This is not necessarily the same as 
the load point (or lowest memory 
address in the program). 


EOF (End Of File). A 3-byte 
number ranging from 0 to 
16,777,216 (16 megabytes), which 
represents the offset to the end of 
the file. If the file is sequential 
(contains no “holes”), the EOF is also 
the length of the file in bytes. 
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epilogue. The last three bytes ofa 
field on a track. These unique bytes 
are used to insure the integrity of 
the data which precedes them. 


Exclusive OR. A logical operation 
which compares two bits to 
determine if they are different. 1 
EOR 0 results in 1.1 EOR 1 results 
in 0. 

field. A group of contiguous bytes 
forming a single piece of data, such 
as a person’s name, his age, or his 
social security number. In disk 
formatting, a group of bytes 
surrounded by gaps. 

file. A named collection of dataona 
diskette or other mass storage 
medium. Files can contain data or 
programs. 

file buffers. In Apple ProDOS, a 
pair of 512-byte buffers used by the 
BASIC Interpreter to manage one 
open file. Included are a buffer 
containing the block image of the 
current index block and one 
containing the image of the current 
data block. File buffers are 
allocated by the BI as needed by 
moving Applesoft’s HIMEM pointer 
down in memory. 

file descriptive entry. A single 
entry ina disk directory which 
describes one file. Included are the 
name of the file, its data type, its 
length, its access restrictions, its 
creation date, its location on the 
diskette, ete. 

filetype. The type of data held bya 
file. Valid ProDOS file types include 
Binary (BIN), Applesoft (BAS), 
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Text (TXT), and System (SYS) files. 
ProDOS supports up to 256 
different file types. 

firmware. A middle ground 
between hardware and software. 
Usually used to describe micro-code 
or programs which have been stored 
in read-only memory (ROM). 

gap. The space between fields of 
data on a diskette. Gaps on an Apple 
diskette contain self-syne bytes. 

garbage collection. The process of 
combining many small embedded 
free spaces into one large area. For 
example, Applesoft performs 
garbage collection on its string 
storage to recover memory allocated 
to strings which have been deleted. 


Global Page. A 256-byte area of 
memory set aside by ProDOS to 
contain system variables of general 
interest. Two Global Pages are 
currently defined: the System 
Global Page at $BF00; and the BI 
Global Page at $BEO0. The 
structure of the Global Pages is 
rigidly defined, allowing external 
programs to communicate with 
ProDOS without depending upon 
release dependent locations. See also 
vectors. 

harderror. Anunrecoverable 
Input/Output error. The data stored 
in the disk sector can never be 
successfully read again. 

head. The read/write head ona 
diskette drive. A magnetic pickup, 
similar in nature to the head ona 
stereo tapedeck, which rests on the 
spinning surface of the diskette. 





hexadecimal/HEX. A numeric 
system based on powers of 16. Valid 
hex digits range from 0 to 9 and A to 
F, where A is 10, B is 11, ..., Fis 15. 
Standard Apple practice is to 
indicate a number as hexadecimal 
by preceding it with a dollar sign. 
$B30 is 11-256s plus 3-16s plus 0-1s, 
or 2864 in decimal. Two 
hexadecimal digits can be used to 
represent the contents of one byte. 
Hexadecimal is used with 
computers because it easily converts 
to binary. 

high memory. Those memory 
locations which have high address 
values. $F FFF is the highest 
memory location. Also called the 
“top” of memory. 

HIMEM. Applesoft’s zero page 
address which identifies the first 
byte past the available memory 
which can be used to store BASIC 
programs and their variables. 


immediate command. A ProDOS 
command which may be entered at 
any time, especially when ProDOS 
is waiting for a command from the 
keyboard. The opposite of deferred 
commands. 


index. A displacement intoa table 
or block of storage. 


index block. A block containing a 
table of block numbers describing 
the order and location of the blocks 
of data within a file. A sapling file 
has one index block describing up to 
256 data blocks. A tree file has a 
master index block which points to 
other index blocks, which in turn 
point to the data blocks in the file. 

instruction. A single step to be 
performed in an assembly language 
or machine language program. 
Instructions perform such 
operations as addition, subtraction, 
Store, or load. 

integer. A “whole” number with no 
fraction associated with it, as 
opposed to floating point. 

intercept. A program which 
logically places itself in the 
execution path of another program, 
or pair of programs. A video 
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intercept is used to re-direct 
program output from the screen toa 
printer, for example. 


interleave. The practice of selecting 


the order of sectors on a diskette 
track to minimize access time due to 
rotational delay. Also called 
“skewing” or interlacing. 


interpreter. A program which 


translates user written commands 
or program statements directly into 
their intended function. Applesoft is 
an interpreter. The ProDOS BASIC 
Interpreter translates ProDOS 
commands into functions such as 
loading, saving, reading or writing 
files. Another name for ProDOS 
Interpreters is System Programs. 


interrupt. A hardware signal which 


causes the computer to halt 
execution of a program and enter a 
special handler routine. Interrupts 
are used to service real-time clock 
time-outs, BRK instructions, and 
RESET. 


I/O (Input/Output) error. Anerror 


which occurs during transmission of 
data to or from a peripheral device, 
such as a disk or cassette tape. 


JMP. A 6502 assembly language 


instruction which causes the com- 
puter to begin executing 
instructions at a different location 
in memory. Similar toa GOTO 
statement in BASIC. 


JSR. A 6502 assembly langauge 


instruction which causes the com- 
puter to “call” a subroutine. Similar 
toa GOSUB statement in BASIC. 

K. A unit of measurement, usually 
applied to bytes. 1 K bytes is 
equivalent to 1024 bytes. 

Kernel. That part of ProDOS which 
provides the basic operating system 
support functions. The Kernel 
resides in the Language Card or 
bank switched memory and consists 
of the MLL. interrupt handler, and 
diskette and calendar/clock device 
drivers. 

key block. The first block ofa 
ProDOS file. 


KSWL. A vector in zero page 
through which input data is passed 
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from the keyboard or a remote 
terminal. 

label. A name associated witha 
location in a program or in memory. 
Labels are used in assembly 
language much like statement 
numbers are used in BASIC. 


language card. An additional 16K 
of RAM added toan Apple II or 
Apple II Plus using a card in slot 0. 
The card gets its name from its 
original use with the Apple UCSD 
PASCAL system and for loading 
other versions of BASIC. Apple Te’s 
have this additional memory built 
in. See also bank switched memory. 

latch. A component into which the 
Input/Output hardware can store a 
byte value, which will hold that 
value until the central processor has 
time to read it (or vice versa). 

link. An address or block pointer in 
an element of a linked chain of data 
or buffers. 

list. A one dimensional sequential 
array of data items. 

load point (LP). The lowest address 
of a loaded assembly language 
program—the first byte loaded. Not 
necessarily the same as the entry 
point address (EPA). 

locked. A file is locked if it is 
restricted from certain types of 
access—usually one which is read 
only. ProDOS provides control over 
file access through the use of 
directory entry bits. 

logical. A form of arithmetic which 
operates with binary “truth” or 
“false”, lor 0. AND, OR, NAND, 
NOR, and Exclusive OR are all 
logical operations. 

LOMEM. Applesoft’s zero-page 
address which identifies the first 
byte of the available memory which 
can be used to store BASIC 
programs and their variables. 

loop. A programming construction 
in which a group of instructions or 
statements are repeatedly executed. 

low memory. The memory locations 
with the lowest addresses. $0000 is 
the lowest memory location. Also 
called the “bottom” of memory. 


LSB/Lo order. Least Significant 
Bit or Least Significant Byte. The 
1’s bit in a byte or the second pair of 
hexadecimal digits forming an 
address. In the address $8030, $30 is 
the Lo order part of the address. 


mark. A 3-byte “byte number” or 
position within a ProDOS file. When 
a file is being read by the MLI.a 
current mark is maintained as well 
as the EOF mark. See also EOF. 


microsecond. A millionthofa 
second. Equivalent to one cycle of 
the Apple II central processor. Also 
written as “psec”. 


MLI (Machine Language 
Interface). The MLI is part of the 
ProDOS Kernel which resides in the 
language card or bank switched 
memory. The MLI performs such 
functions as OPENinga file, 
WRITING toa file. or 
DESTORYing a file. 


monitor. A machine language 
program which always resides in 
the computer and which is the first 
to receive control when the machine 
is powered up. The Apple monitor 
resides in ROM and allows 
examination and modification of 
memory ata byte level. 


MSB/Hiorder. Most Significant 
Bit or Most Significant Byte. The 
128’s bit of a byte (the left-most) or 
the first pair of hexadecimal digits 
in an address. In the byte value $83, 
the MSB is on (isa 1). 

nibble/nybble. A portion of a byte, 
usually 4 bits and represented by a 
single hexadecimal digit. $FE 
contains two nibbles, $F and $E. 

null. Empty, having no length or 
value. A null string is one which 
contains no characters. The null 
control character ($00) produces no 
effect on a printer (also called an 
idle). 

object code. A machine language 
program in binary form, ready to 
execute. Object code is the output of 
an assembler. 

object module. A complete machine 
language program in object code 
form, stored as a file on a diskette. 





offset. The distance from the 
beginning of a block of data toa 
particular byte or field. Offsets are 
usually given beginning with 0, for 
the first byte, 1 for the second, etc. 
Also known as a displacement. 


opcode, operation code. The three 
letter mnemonic representing a 
single assembly language 
instruction. JMP is the opcode for 
the jump instruction. 


operating system. A machine 
language program which manages 
the memory and peripherals 
automatically. simplifying the job of 
the applications programmer. 


OR. The logical operation 
comparing two bits to determine if 
either of them are 1. 1 OR 1 results 
in 1 (true), 1 OR 0 results in 1,0OR 
0 results in 0 (false). 


overhead. The space required by 
the system, either in memory or on 
the disk, to manage either. The boot 
blocks, Volume Directory, and 
Volume Bit Map are part ofa 
diskette’s overhead. 


page. 256 bytes of memory which 
share a common high order address 
byte. Zero page is the first 256 bytes 
of memory ($0000 through $00FF). 


parallel. A communication mode 
which sends all of the bits in a byte 
at once, each over a separate line or 
wire. Opposite of serial. 


parameter list. An area of storage 
set aside for communication 
between a calling program and a 
subroutine. The parameter list 
contains input and output variables 
which will be used by the 
subroutine. 


parity. Ascheme which allows 
detection of errors in a single data 
byte, similar to checksums but ona 
bit level rather than a byte level. An 
extra parity bit is attached to each 
byte which is asum of the bits in the 
byte. Parity is used in expensive 
memory to detect or correct single 
bit failures, and when sending data 
over communications lines to detect 
noise errors. 
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parse. The process of interpreting 
character string data, such asa 
command with keywords. 


patch. A small change to the object 
code of an assembly language 
program. Also called a “zap”. 


pathname. A string describing the 
path ProDOS must follow to find a 
file. A fully qualified pathname 
consists of the volume name 
followed by one or more directory 
names followed by the name of the 
file itself. If a partial pathname is 
given, a default prefix is attached to 
it to form a complete pathname. See 
also prefix. 


physical record. A collection of 
data corresponding to the smallest 
unit of storage on a peripheral 
device. For disks, a physical record 
ig a sector. 


pointer. The address or memory 
location of a block of data or a single 
data item. The address “points” to 
the data. A pointer may also bea 
block number, such as the pointer to 
the Volume Bit Map in the Volume 
Directory Header. 


prefix. Asystem maintained default 
character string which is 
automatically attached to file names 
entered by the user to form a 
complete pathname. See also 
pathname. 


prologue. The three bytes at the 
beginning of a disk field which 
uniquely identify it from any other 
data on the track. 


PROM (Programmable Read Only 
Memory). PROMs are usually 
used on controller cards associated 
with peripherals to hold the driver 
program which interfaces the 
device to applications programs. 


prompt. An output string which lets 
the user know that input is 
expected. An “*” is the prompt 
character for the Apple monitor. 


pseudo-opeode. A special assembly 
language opcode which does not 
translate into a machine instruction. 
A pseudo-opcode instructs the 
assembler to perform some 
function, such as skipping a page in 
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an assembly listing or reserving 

data space in the output object code. 
RAM (Random Access 

Memory). Computer memory 

which will allow storage and 

retrieval of values by address. 


random access. Direct access. The 
capability to rapidly access any 
single piece of data on a storage 
medium without having to 
sequentially read all of its 
predecessors. 


recal. Recalibrate the disk arm so 
that the read/write head is 
positioned over track zero. This is 
done by pulling the arm as far as it 
will go to the outside of the diskette 
until it hits a stop, producing a 
“clacking” sound. 

reference number (REF 
NUM). Anarbitrary number 
assigned to an open file by the MLI 
to simplify identification in later 
calls. 

register. A named temporary 
storage location in the central 
processor itself. The 6502 has 5 
registers; the A, X, Y,S.and P 
registers. Registers are used by an 
assembly language program to 
access memory and perform 
arithmetic. 


relocatable. The attribute of an 
object module file which contains a 
machine language program and the 
information necessary to make it 
run at any memory location. 


return code. <A numeric value 
returned from a subroutine, 
indicating the success or failure of 
the operation attempted. A return 
code of zero usually means there 
were no errors. Any other value 
indicates the nature of the error, as 
defined by the design of the 
subroutine. 

ROM (Read Only 
Memory). Memory which hasa 
permanent value. The Apple 
monitor and Applesoft BASIC are 
stored in ROM. 


sapling. A ProDOS file which 
requires only one index block (2 to 
256 data blocks). A sapling ranges 


from 513 bytes to 131,072 bytes in 
length. See also seedling and tree. 


search. The process of scanning a 
track for a given sector. 


sector. The smallest updatable unit 
of data on a disk track. One sector on 
an Apple Disk IT contains 256 data 
bytes. 


sector address. A disk field which 
identifies the following sector data 
field in terms of its volume, track, 
and sector number. 


sector data. A disk field which 
contains the actual sector data in 
nibbilized form. 


seedling. A ProDOS file which has 
only a single data block (512 bytes). 
A seedling file does not require 
index blocks. See also sapling and 
tree. 


seek. The process of moving the disk 
arm to a given track. 


self-syne. Also called “auto-syne” 
bytes. Special! disk bytes which 
contain more than 8 bits, allowing 
synchronization of the hardware to 
byte boundaries when reading. 

sequential aceess. A mode of data 
retrieval where each byte of data is 
read in the order in which it was 
written to the disk. 

serial. A communication mode 
which sends data bits one at a time 
over a single line or wire. As 
opposed to parallel. 

shift. A logical operation which 
moves the bits of a byte either left or 
right one position, moving a 0 into 
the bit at the other end. 

skewing. The process of 
interleaving sectors. See interleave. 


softerror. <A recoverable I/O error. 
A worn diskette might produce soft 
errors occasionally. 

SOS (Sophisticated Operating 
System). The standard operating 
system for the Apple IIT computer. 

source code. A program ina form 
which is understandable to humans; 
in character form as opposed to 
internal binary machine format. 
Source assembly code must be 
processed by an assembler to 
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translate it into machine or “object” 
code. 


sparse file. A file with random 
organization (see random access) 
which contains areas which were 
never initialized. A sparse file 
might have an End Of File mark of 
16 megabytes but only contain 
several hundred bytes. 


state machine. A process (in 
software or hardware) which 
defines a unique target state, given 
an input state and certain 
conditions. A state machine 
approach is used in the ProDOS 
BASIC Interpreter to keep track of 
its video intercepts and by the 
hardware on the disk controller 
card to process disk data. 


strobe. The act of triggering an I/O 
function by momentarily 
referencing a special! I/O address. 
Strobing $C030 produces a click on 
the speaker. Also called “toggling”. 


subroutine. A program whose 
function is required repeatedly 
during execution, and therefore is 
called by a main program in several 
places. 

system disk. A ProDOS volume 
which contains the system files 
necessary to allow ProDOS to be 
booted into memory. Normally, the 
PRODOS and BASIC.SYSTEM 
files are necessary. A STARTUP 
program may also be present. 

system program. A ProDOS 
program, written in machine 
language, which acts as an 
intermediary between the user and 
the ProDOS Kernel. 
BASIC.SYSTEM, FILER, and 
CONVERT are all examples of 
System Programs. See also 
interpreter and BI. 

table. A collection of data entries, 
having similar format, residing in 
memory. Each entry might contain 
the name of a program and its 
address, for example. A “lookup” 
can be performed on such a table to 
locate any given program by name. 

toggle. The act of triggering an I/O 
function by momentarily 


referencing a special I/O address. 
Toggling $C030 produces a click on 
the speaker. Also called “strobe”. 


tokens. A method where human 
recognizable words may be coded to 
single binary byte values for 
memory compression and faster 
processing. BASIC statements are 
tokenized, where hex codes are 
assigned to words like IF, PRINT, 
and END. 


track. One complete circular path of 
magnetic storage on a diskette. 
There are 35 concentric tracks on an 
Apple diskette. 


translate table. A table of single 
byte codes which are to replace 
input codes on a one-for-one basis. A 
translate table is used to convert 
from 6-bit codes to disk codes. 


tree. A ProDOS file which requires 
several index blocks (131,073 to 
16,777,216 bytes of data). See also 
index block, seedling, and sapling. 


TTL (Transistor to Transistor 
Logic). A standard for the 
interconnection of integrated 
circuits which also defines the 
voltages which represent 0’s and 1’s. 


unlocked. A file which allows all 
types of access (READ, WRITE, 
DELETE, RENAME  etc.). See 
also locked. 


utility. A program which is used to 
maintain, or assist in the 
development of, other programs or 
disk files. 


vector. A collection of pointers or 
JMP instructions at a fixed location 
in memory which allows access toa 
relocatable program or data. 


volume. An identification for a 
diskette, disk platter, or cassette, 
containing one or more files. 

Volume Directory. The first 
directory on a disk volume. Also 
called the “root” directory. All other 
directories must be reached by first 
reading the Volume Directory. 


warmstart. A restart of a program 
which retains, as much as is 
possible, the work which was in 
progress at the time. 
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ZAP. From the IBM mainframe zero page. The first 256 bytes of 
utility program, SUPERZAP. A + memory ina 6502 based machine. 
program which allows updates toa Zero page locations have special 
disk at a byte level, using significance to the central! 
hexadecimal. processor, making their 


management and assignment 
critical. 


/RAM (random access memory) 
devicedriver 7-2, 7-7, 7-8 
drive 5-3, 5-9, 6-6, 7-1, 7-7, 7-9, 7- 
10, 7-12 
volume 7-7, 7-10 
80-column card 2-2, 2-4, 7-12, 7-27, 8- 
7, A-36, A-37 
80-column soft switches 7-12 
access bits 4-9, 4-12, 4-30, chap. 6 
address field 3-8, 3-11, 3-13, 3-14, A- 
4, A-5, C-1, C-2, C-7 
advantagesof ProDOS 2-5 
alternate 64K memory 5-9, 7-7 
arm (see disk) 
AppleII 5-9, 7-12 
Apple II Plus 5-1, 5-9, 6-63 
Apple IIc 5-9, 6-6, 7-7, D-1 
Apple Tle 5-1, 5-9, 6-63, 7-7 
reference manual A-26 
ROM A-36 
Thunderclock 2-2, 5-5, 7-14, 7-27 
Apple III 5-9, 6-12, 6-63, E-1 
Applesoft 5-2, 5-7, 5-11, 6-31, 6-35, 7- 
5, (see also file types) 
& 5-7 
BASIC 5-1,5-4 
enhancement aid programs 2-8 
file 2-7, (see also file types) 
motherboard ROM 5-3 
variables, saving and restoring 2-2 
AppleWorks 6-24, 6-30, 6-34, E-4 
automated programs B-4, B-5 
autostart 5-7 
auxiliary data buffer C-3,C-5 


, 7-12 


INDEX 


auxiliary memory 7-1, 7-2, 7-3, 7-7, 
7-8 
availableRAM 5-3 
bank switched memory 2-8, 5-1, 5-4, 
5-9, 6-7, 6-18, 6-19, 7-27, 8-8 
BAS 4-12, A-26 
BASIC 1-2, 2-2, 2-5, 2-6, 2-7, 2-8, 4- 
14, 4-19, 4-20, 4-23, 4-24, 4-31, 5-4, 
5-6, 5-9, 5-11, 7-4, 7-19, A-2, A-22, 
A-26, E-1, E-2, (see also file types) 
BASIC interpreter intercepts 2-7, 2-8, 
5-1, 5-2, 5-3, 5-4, 5-8, 6-2, 7-2, 7-4, 
7-5, 7-14, 7-18, 7-24, 7-27, A-30 
BASIC.SYSTEM 5-10, 5-11, 7-10, 7- 
19, 7-21, 7-22, 7-24 
BI 5-6, 5-7, 5-10, 5-11, 5-12, 6-1, 6-31, 
6-61, 6-64, chap. 7, 8-2, A-2, A-30, 
A-31 
buffer allocation subroutine 7-4, 
7-14 
command scanner 5-7 
Global Page chap. 5, 6-62, 6-65, 7- 
4, 7-6, 7-21, A-30 
loader 5-9, 5-10, 5-11 
relocator 5-10, 5-11 
syntax scanner 7-6 
bitassignment 6-10,6-11 
BIN files (see files) 
bit map 5-2, 5-6, 6-27, 6-60, 6-62, 6- 
64, 7-11, 7-12 
bitecells 3-4, 3-5, 3-9 
bit-slip marks 3-14 
blocks 3-1, 3-3, 3-15, 3-18, 3-19, chap. 
4, 5-5, 5-9, 5-10, 7-10, 7-19, 7-285, 7- 
26, A-2 
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block access 3-20, 6-1, 6-6 
block number 3-16, 3-19, 6-7, 6-8, 6- 
9, 6-10, 6-11, 6-18, 6-19, 6-20, A-25, 
A-26 
boot (see disk) 
boot image 4-6 
boot loader E-3 
Boot ROM __ 5-8, 5-9, 5-11 
bootstrap loader 4-3, 4-31, 5-8, 7-19 
breaking protected software B-1 
BRK 5-7 
BSAVE command (see commands) 
buffer 3-3, 7-2, 7-4, 7-5, 7-7, 7-10, 7- 
11, 7-14 
circular 7-16, A-36 
pointer 6-7 
BUGBYTER 7-27 
CHAINing E-2 
checksum 3-8, 3-13. 3-14, 4-31, 4-32, 
C-12 
clock 5-3, 7-13. 7-20 
elock/calendar 5-5, 6-13, 6-21 
clock driver 7-2 
coldstart 5-11 
command handlers 7-5, 7-6, 7-7, 8-3, 
A-2, A-30, A-31 
computational overhead time 4-33 
controller card 4-31, 5-8, 5-9, 6-59, 7- 
25, D-2 
CONVERT 7-10 
copy programs B-5 
CP/M 3-1 
creation, dateand timeof 4-8, 4-28, 
chap. 6 
CSWL/H_ 5-11, 6-65 
customizing ProDOS 2-2, chap. 7 
data 
blocks 4-11, 4-14, 4-15, 4-16, 4-18, 
4-19, 4-22 
field 3-8, 3-11, 3-12, 3-13, 3-14, A-4, 
A-5 
register 3-6, 3-7, 3-10. 6-2, 6-3, 6-5, 
D-2, D-3, D-4, D-5, D-6, D-8, D-9 
date/time routine 6-13, 8-5 
date/time of creation chap.6 
date/time of last modification chap. 
6 
DEALLOC INTERRUPT 7-15 
decoding 3-8, 3-11, 3-12 
device 
connect 6-8, 6-9, 6-10, 6-11, 6-19, 6- 
20, 6-59, 6-62, A-23 
drivers 2-4, 3-3, 3-16, 3-18, 3-19, 5- 
5, 6-6, 6-7, 6-18, 6-59, 7-3, 7-7, 7-10, 
7-20, 7-25, 7-27, 8-6, C-1, C-5, E-3 


handler 6-18, 6-19 
independent 2-1, 2-4, 3-1,5-5 
number 7-8, A-5 
signature 7-13, 7-14 
specific code 3-1 
status 3-1 
device driver parameters 6-8, 6-9, 
direct access 6-1, 6-2 
direct block I/O A-2 
direct READ 6-45, 6-46, 6-48 
direct WRITE 6-48 
directory 2-4, 2-8, chap. 4, 5-9, 6-13, 
A-2 
blocks 4-6 
damage A-19 
entry 2-7, 2-9, 4-4, 4-12, 4-15, 4-17, 
4-19, 4-20, 4-23, 6-22, 6-50, A-25, 
A-26, A-27 
file 6-54, 7-23 
full 6-62 
header 6-22 
disk 
access 2-3, 4-34 
arm 6-4 
backup 4-31, 4-32 
boot 5-7, 5-8, 5-12, 7-10, 7-11. 7-12, 
7-19. 4-21, 7-22 
controller card 4-3, 5-9, 6-1. D-1 
damaged 4-30, 4-31, 4-32, A-9, 
A-27 
device 7-14 
drive 2-5, 5-5, 5-6, 7-7, 7-20 
format 4-10, 4-30, 4-31, 4-32, 4-34, 
7-8, 7-14, 7-25, A-1, A-26 
full 6-25, 6-49, 6-62 
harddisk 4-3, 4-5, 4-26, 5-8, 5-9, 6- 
6, 7-14 
head 4-33 
protection schemes _ B-1, B-6, (see 
also protection schemes) 
repair A-1,A-9 
swapping 2-8 
diskette organization 3-3 
DOS 2-1, 4-33, 7-18, E-1 
3.3 2-1 
deficiencies of 2-1 
File Manager E-2 
standardization 2-2 
DUMBTERM (see utility programs) 
DUMP (see utility programs) 
EDASM_ 7-10, 7-27 
emergency repairs 4-30 
emulation mode 5-9 
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encoding C-5 
4dand4 C-1,C-2 
5and3 C-2 
6and2 C-2,C-3 
ofdata C-1 
epilogue 3-8, 3-13, 3-14 
error 
codes 6-59, 8-2, 8-4, A-20 
handling 8-2, A-9 
I/O 4-80, 4-31, 4-32, chap. 6, 7-25, 
A-4, A-5, A-20, A-28, A-25, A-26, 
E-1 
message 7-22 
number 8-2 
soft 4-31 
example programs (see utility 
programs, customizing ProDOS) 
exclusive-ORing C-7,C-9, C-12 
EXERCISER 7-27 
extended 80-column card 2-5, 5-5, 
7-7 
externalcommand 7-6 
EXTERNCMD 7-6, 7-7, 8-2, A-30, 
A-31 
FCB (see File Control Block) 
FIB (see utility programs) 
file 
Applesoft 2-7 
attributes 6-13 
BAS 4-23, 4-24 
BIN 2-6, 4-12, 4-20, 4-22, A-26, E-4 
buffers 2-8, 5-3, 5-4, 5-6, (see also 
Machine Language Interface 
function codes) 
control block 6-41, 6-49, 6-59 
count 4-9, 4-12 
creating 7-23, 7-24, 7-27 
descriptive entries 4-6, 4-10, 4-14, 
4-32 
directory 6-60 
DIR 4-26, 7-23 
EXEC 5-6, 8-3 
HELLO E-2 
/Obuffers 7-4 
locked 4-12 
management interfaces 2-7 
managementsystem 2-4, 2-5 
opening of 2-8, 5-4 
pathname 2-8, 4-28 
random access text 2-6, 4-21 
saplings 4-10, 4-11, 4-13, 4-15, 4- 
17, 4-19, 4-32, 6-36, 6-60 
seedling 2-9, 4-10, 4-11, 4-13, 4-14, 
4-15, 4-19, 4-32, 6-25, 6-36, 6-60, 
A-26 


sparse files 4-19, 4-21, 6-54, 6-56, 
E-2 
STARTUP 5-12, E-2 
structures 2-2, 4-13, 4-15, 4-17, 
4-19 
tree 4-10, 4-11, 4-13, 4-17, 4-19, 4- 
82, 6-36, A-26 
FILER 6-6, 7-10, 7-25, 7-26 
filetypes 2-7, 4-10, 4-19, 4-24, 6-60, 
7-10 
flags 5-6 
FORMAT (see utility programs) 
format alterations B-2 
fragmentation 4-33, 4-34 
free blocks 4-3, 4-5, 4-32 
FREEBUFR 7-5 
freesubroutines 5-7 
front door methed B-7, B-8 
function code (see Machine 
Language Interface function 
code) 
gaps 3-8, 3-11, 3-13, 3-15, 3-19 
garbage collection 2-6, 2-8, 5-4, 8-3 
general purpose buffer 5-3, 5-4, 5-1 
7-4, 7-9, 7-10 
genericsignature 7-13 
GETBUFR 7-4 
GETLN 7-3 
input line buffer 7-2 
Global Pages (see BI Global Page or 
System Global Page) 
Group Code Recording D-1 
half tracks 3-2, B-4 
harddisk 2-1, 4-1, 4-26 
hardware 
board B-7,B-8 
eard B-2 
headerentry 4-6, 4-26 
HELLO (see files) 
hiding thecode B-7 
HIMEM 2-8, 4-25, 5-2, 5-3, 5-4, 5-7, 
7-4, A-31, B-2 
HIRES 
double graphics 7-7 
primary buffer 7-7 
secondary buffer 17-7 
IN# 5-6,7-14 
index blocks 2-9, 4-15, 4-16, 4-17, 4- 
18, 4-32, 4-38, 6-36, 6-47, 6-54, A- 
2, A-25, A-26, A-27 
index holes 3-3 
input vector 8-2 
integer BASIC 2-7, 5-4, E-2 
Integrated Woz/Wendell 
Machine D-1 
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intercept 8-2, 8-3 

interfacecard 5-5 

interleaving 3-15, 3-16, 3-18 
inter-block 3-16, 3-18 
intra-block 3-16, 3-18 

interpreter 5-10, 7-10, 7-11, 7-12 


interrupt 2-2, 2-4, 5-5, 5-6, 6-18, 6-19, 
7-14, 7-15, 7-16, 7-17, 8-7, A-2, A- 
35, A-37, A-36, B-6 

handler 6-13, 6-15, 6-16, 6-59, 6-61, 
7-11, 7-15, 7-19, 8-6, E-3 

IRQ maskable 5-7, 6-15 

routine 7-16, 7-17, 8-8 


vector table 6-59, 7-15 
I/Obuffer 6-8, 6-45, 6-61, A-31 
I/Oerror (see error) 
1/Oselectaddress A-1 
IRQhandler 8-6 
joystick 7-13 
KBAKVER 7-11 


Kernel 2-5, 2-7, 2-8, 4-31, 5-1, 5-2, 5- 
8, 5-4, 5-5, 5-8, 5-9, 5-10, 5-11, 6-12, 
6-18, 6-20, 7-3, 7-7, 7-10, 7-11, 7- 
15, 7-17, 7-18, 7-19, 7-27, 8-8, E-3 

key block 4-4, 4-6, 4-7, 4-11, 4-12 
A-23 

keyword 5-6, 7-6, 8-4, E-2 


KSWL/H 5-11, 6-65 
KVERSION 7-11 


languagecard 2-8, 5-1, 5-3, 5-4, 5-6, 
5-9, 6-17, 6-18, 6-19, 7-1, 7-12, 7- 
27, 8-8 

LEVEL 6-43, 6-49 to 6-51, 6-59 

logic state sequencer D-1, D-2, D-8 


MACHID 7-7, 7-12, 7-27 
machineID 5-6 
Machine Language Interface 3-18, 4- 
31, 5-8, 5-4, 5-5, 5-6, 5-7, chap. 6, 7- 
2, 7-10, 7-12, 7-16, 7-17, 7-23, 7-24, 
8-4, 8-5, 8-7, A-2, A-31, A-36, A- 
37, E-2, E-3 
buffers 7-11 
function codes 6-12 to 6-16, 6-59 
Macintosh 2-4, D-1 
manuals 
BASIC Programmming With 
ProDOS 1-1, 1-2, 6-1 
Beneath Apple DOS 1-2, 8-1 
ProDOS User's Manual 1-1, 1-2 
ProDOS Teehnical Reference Man- 
ual (for the Apple [Tfamily) 1-2 
Understanding the Apple IT 3-4, 
D-8 
MAP (see utility programs) 
master index block 4-11, 4-17, 4-18, 
4-22, A-26 


memory 
bitmap 2-5, 5-2, 5-6, 5-11, 7-11, 8-6 
page boundaries 6-6 
MLI (see Machine Language 
Interface) 
modem 7-13 
monitor 5-7, 7-19, A-3, A-37 
ROM_ 5-9, 7-27 
most significant bit(MSB) 6-45, D-8 
motherboard ROM 2-7, 7-15, 7-23 
motor 6-4 
MSB (see Most Significant Bit) 
multiple buffering (see ProDOS) 
network 7-13 
nibble C-1 
copiers B-2, B-5, B-7 
copy programs A-9, B-6 
counting B-5 
non-maskable interrupt 5-7 
online devices list 7-8 
open file E-2, E-3 
output vector 8-2 
overhead 2-1, 4-2, 4-33 
padding 4-20 
parallelcard 7-13 
parameter 8-4,8-5, B-6, B-7 
count chap.6 
list chap.6 
PASCAL 2-2, 2-3, E-4 
patching 7-19, 7-20, 7-21, 7-25, 7-26, 
A-2, A-27 
pathname 2-8, 4-26, 4-27, 4-28, 4-34, 
chap. 6, 7-5, 7-7, 7-12, 8-4 
PBITS 7-6,7-7 
peripheral 
ealendar/clock 2-4 
eard 5-9, 7-13, 7-15 
drivers 7-13 
phases 3-2, 6-2, 6-4 
physical interleaving 3-15, 3-16 
physical sectors 5-9 
power-up byte 5-7, 7-11 
PR# 5-6, 7-14 
prefix 2-8, 4-28, 7-7, 7-12 
prenibble A-1,C-5 
PreDOS 
advantages 2-5 
commands 5-1, 5-4 
devicedriver 6-1 
disadvantages 2-7 
filename E-1 
loader 5-9, 5-10, 7-7 
multiple buffering 2-3 
Program Logic Supplement 5-12, 
8-1 
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relocator 5-9, 5-10, 7-7 
system files 4-3, 5-10 
version 4-8, 5-5, 5-6, 7-11, 7-19, 7- 
21, 7-24 
ProFile 4-1, 4-5, 6-6, 7-14 
prologue 3-13, 3-14 
promptcharacter 5-11 
protection A-4, appendix B 
quarter tracks B-4 
QUIT code 2-8, 5-4, 6-23, 7-1, 7-3, 7- 
12, 7-20 
quit vector 5-5 
/RAM_ (see top of index) 
read 6-8, 6-43 
block 6-7 
pulse D-6, D-8, D-9 
recalibrates 5-9 
register (see data register) 
rename 4-9, 4-12, 4-30, A-27 
record length 2-6, 4-14, 4-15, 4-20, 
6-24 
reference number chap.6 
relocatable object module 6-24, 6-31, 
6-35 
repairing diskettes (see emergency 
repairs) 
RESET key 4-31, 4-32, 7-11, 7-12 
reset protection B-6 
RESET veetor 6-64, 7-11 
RESTORE 4-24, (see also file types) 
return code chap. 6, A-20 
ROM_ 5-4, 5-8, 6-6, D-1, D-2, D-5, D-6 
map 8-7 
rotation delay 4-33, 4-34 
RUN command (seesmart RUN 
command) 
run-time environment 2-7 
RWTS  E-2 
sapling (see file) 
savearea 8-3, 8-7 
sectors, allocationof 4-1 
seedling (see file) 
seek delay 4-33, 4-44 
select drive 6-2 
self-syne bytes 3-7, 3-8, 3-9, 3-10, 3- 
11, 3-12 
sequential blocks 3-16 
sequential form 4-19 
serial 7-13 
serial interfacecard A-2, A-35 
signature (see protection) 
skewing 4-1, 4-33, 4-34 
slot 5-5, 5-6, 5-9, chap. 6, 7-7 
smart RUN command 2-5, 7-10, 7-22 
softsectoring 3-3 
software interleaving 3-16 


SOS 1-3, 2-4, 4-1, 4-11, 4-24, 6-12, 
E-1 
sparse (see file) 
special sync bytes B-6 
speech device 7-13 
spiral tracks B-4 
STARTUPfile 7-22 
statemachine D-2, D-3, D-5, D-8 
STATUS. 6-6, 6-7, 6-8 
status register A-36 
stepper phase 6-4 
storage type 4-8, 4-10, 4-15, 4-28, 
4-33 
strings 5-4, 8-3 
subdirectory 4-4, 4-7, 4-9, 4-10, 4-11, 
4-12, 4-26, 4-27, 4-28, 4-29, 4-30, 
6-24 
header 4-10, 4-28, 4-29, 4-30 
name 4-28 
subindex block 4-17, 4-19, 4-22 
supplement 1-3, 8-2, 8-8, 8-9 
switches 6-2,6-3 
synchronized tracks B-5 
SYS 4-12, 7-10, 7-11, 7-19, 7-27 
system 
bitmap (see bit map) 
calls 2-2, 2-4, 7-1 
death handler 8-5, 8-8 
errorhandler 8-5 
Global Page 2-4, 2-5, 5-2, 5-3, 5-5, 
6-15, 6-17, 6-21, 6-43, 6-50, 6-51, 6- 
57, 6-61, 6-63, 7-2, 7-7, 7-8, 7-11, 7- 
12, 7-15, 7-16, 7-20, 8-1, 8-2, 8-5, 
A-37, E-3 
program 5-4, 7-10, A-87, 6-24, 6-31 
vector area 7-2 
terminalemulator A-2, A-35 
textfiles 2-6, 6-24, 6-80, 6-31, 6-34, 6- 
35, E-4 
tree (see files) 
Thunderclock (see Apple IIe) 
TRACE 2-8, 8-3 
track formats 3-3 
translate C-8 
two way mapping C-9 
TXT 4-12, 4-19, 4-20, 4-31, A-26 
TYPE (see utility programs) 
Understanding the Apple IT 3-4, D-8 
Understanding the Apple Ile 6-8 
unitnumber 6-7, 6-8, 6-9, 6-10, 6-11, 
6-13, 6-18, 6-19, 6-20 
user data page C-5 
user written 
commands 2-4 
programs 5-2 
utilities 2-2, 2-4, 2-5, 4-24, 4-32, 4-33 


I-6 Beneath Apple ProDOS 


utility programs 

DUMBTERM A-2, A-35, A-36, A- 
37 

DUMP A-1,A-4, A-5, A-31 
FIB A-2, A-4, A-25, A-26, A-27 
FORMAT 6-6,6-7, 6-8, A-2, A-9 
MAP A-2, A-22 

TYPE A-2, A-30, A-31 

ZAP A-2, A-19, A-20, A-25, A-26 

VAR 4-12, 4-25 

variables 

ondisk 2-5 

VCB (see Volume Control Block) 

vector 5-5, 5-7, 5-12 

VO 5-6 

versionnumber 5-9 


volume 2-4, 2-4, 2-8, 3-18, 4-1, 4-2, 4- 
8, 4-6, 4-8, 4-13, 4-26, 4-28, 4-32, 4- 
33, 4-34, 5-9, 7-1, 7-7, 7-8, 7-10, 
7-14, 7-19 

bit map 4-3, 4-4, 4-5, 4-9, 4-32, 4-38, 


4-9 
A-2, A-22, A-23, A-27 
Control Block 6-38, 6-41, 6-61 


directory chap. 4, 6-25, 6-26, 6-28, 
6-29, 6-36, 6-43, 7-11, 7-27, A-22, 
A-28, A-26 

directory header 4-8, 4-9, 
4-10,4-13, 

name 4-8, 6-37, A-23 

number E-2 

spaceallocation 4-5 

VPATH 1 7-6 
warmstart vector 8-2 
write 6-8 
block 6-7 
head 4-34 
6-8, 6-9, 6-11, 6-20, 
28, 6-49 to 6-51, 6-59, 


a 
Pes 


6- 62, D- -6 

XCNUM 7- 6, 7-7 

XLEN 7-6, 7-7 

XTERNADDR 7-6, 7-7 

ZAP 4-382, 4-33, 7-19, (see also utility 
programs) 

zero page 5-11, 7-1, 7-3, 7-15 


Notes 


Beneath 
Apple 
ProDOSs 


REFERENCE 
CARD 


Second Printing, March 1985 


eS QUALITY SOFTWARE 


21601 Marilla St 


DIRECT USE OF THE DISKETTE DRIVE 


ProDOS Hardware Addresses 
“OFF” SWITCHES “ON” SWITCHES 


BASE BASE 
SWITCH | ADDRESS|FUNCTION |ADDRESS|FUNCTION 


Phase 0 off Phase 0 on 

Phase 1 off Phase 1 on 

Phase 2 off Phase 2 on 
Phase 3 on 
Drive on 
Select drive 2 
Load data 
register 
Write 


Enable read sequencing. 

Shift data register every four cycles 
while writing. 

Check write protect and initialize 
sequencer for writing. 

Load data register every four cycles 
while writing. 





Address Ranges For Slots 


SLOT ADDRESS 

NUMBER RANGE 
$CO80—$C08F 
$C090—$CO9F 
$COAO—SCOAF 
$COBO—$COBF 
$COCO—$COCF 
$COD0—$CODF 
$COEO—$COEF 
$COFO—SCOFF 





ma OS 








panel 4 Also See Pages 6-2 to 6-3 


ProDOS Block Conversion Table for Diskettes 


PHYSICA 
SECTOR — 0&2 4&6 8&A C&E 1&3 5&7 9&B D&F 
TRACK 0 000 001 002 003 004 005 006 ‘7 
TRACK 1 008 009 QOA 00B 60C 00D 0OE OOF 
TRACK 2 010 011 012 013 014 015 016 017 
TRACK 3 018 019 OLA 01B 01C 01D O1E OIF 
TRACK 4 020 021 0 023 024 025 026 027 
TRACK 5 028 029 02A 02B 02C 02D 02E 02F 
TRACK6 030 031 032 033 034 035 036. 037 
TRACK7 038 039 038A 03B 03C 03D 08E 03F 
TRACK8 040 041 042 043 044 045 046 047 
TRACK 9 048 049 O4A 04B 04C 04D 04E O4F 
TRACK A 050 051 052 053 054 055 056 057 
TRACK B 058 059 054A 05B 05C 05D 05E 05F 
TRACK C 060 061 062 063 064 065 066 7 
TRACK D 068 069 O6A 06C 06D 06E 06F 
TRACK E 070 071 072 073 074 075 076 077 

078 079 O7A 07B 07C 07D O7E O7F 
TRACK 10 080 081 082 084 085 086 087 
TRACK 11 088 089 08A 08B 08C 08D 08E 08F 
TRACK 12 090 091 092 093 094 095 096 097 
TRACK 13 098 099 09A 09B 09D 09E O9oF 
TRACK 14 0A0 OAl 0A2 0A3 0A4 0A5 OAG6 OAT 
TRACK 15 0A8 OA9 OAA OAB OAC 0AD OAE OAF 
TRACK 16 OBO OBI OB2 0B3 0B4 OBS OB6 OB7 
TRACK 17 OBs OBS OBA OBB OBC OBD OBE OBF 
TRACK 18 0co 0cl 0c2 0C3 0c4 0C5 0C6 OCc7 
TRACK 19 0c8 0c9 OCA 0cB occ ocD 0c OCF 
TRACK 1A obo 0D1 oD2 0D3 0D4 0D5 oD6 0D7 
TRACK 1B oDs oD9 ODA ODB ODC ODD ODE ODF 
TRACK 1C 0E0 0E} OE2 0E3 0E4 OE5 OE6 OE7 
TRACK 1D 0E8 0E9 OEA 0EB 0EC OED OEE OEF 
TRACK 1E OFO OF 1 OF2 OF3 OF4 OFS OF6 OFT 
TRACK IF OF8 OFS OFA OFB OFC OFD OFE OFF 
TRACK 20 100 101 102 103 104 105 106 107 
TRACK 21 108 109 10A 10B 10C 10D 10E 10F 
TRACK 22 110 111 112 113 114 115 116 117 

Also See Page 3-17 
DIRECTORY HEADERS 








STORAGE_TYPE 
NAME_LENGTH 


ee (15 BYTES) 


RESERVED (8 BYTES) 
CREATION 
DATE 
CREATION 
TIME 
VERSION 


+$04 






+$05 














+$14 


+$1C 


+$1E 





+$20 





+0/1: Previous block 
+2/3: Next block 


STORAGE 
TYPE: 


$FI = Vol Dir 
$El = subdir 
Where | = length 
of volume name 


DATE: YYYYYYYM MMMDDDDD 


$21. | yen TIME: OOOHHHHH OOMMMMMM 
ACCESS 
+822 | ACCESS BITS: | DNBOOOWR 
ENT! D = Destroy W =Write 
+$23 N=Rename R= Read 
LENGTH a ae 
ENTRIES 
*$24 | PER BLOCK 
FILE 
io COUNT SAME AS Vol Dir 
$27 BIT MAP PARENT 
POINTER POINTER 
bs TOTAL PARENT PARENT 
BLOCKS ENT NUM ENT LEN 





Vol Dir 





Sub Dir 


panel 2 Also See Pages 4-8 to 4-9 


FILE DESCRIPTIVE ENTRY 







STORAGE_TYPE STORAGE $1! =Seedling 






+800 | NAME LENGTH TYPE: $21 = Sapling 
$31 = Tree 
$01 ae (15 BYTES) $DI = Dir 





Where | = length 
of volume name 







FILE 
TYPE 









+$10 
FILE $04 = TXT 
TYPE: $06 = BIN 
KEY BLOCK POINTER SOF =DIR 
$FC = BAS 
BLOCKS IN USE $FD = VAR 
$FF =SYS 






DATE: YYYYYYYM MMMDDDDD 
TIME: OOOHHHHH OOMMMMMM 


ACCESS 
BITS: ONBOOCOWR 
D=Destroy W=Write 












N=Rename_ R = Read 
VERSION By PRONUe 
AUX TXT = Record Len 
TYPE: BIN 
BAS > Load Address 
VAR 
($2000) 






MODIFY DATE 
MODIFY TIME 
DIR HEAD POINTER 


Also See Pages 4-10 to 4-13 






VOLUME BIT MAP 


01234567 89... —»> 


tif bit is 1, Block 0 is free 
0, Block 0 is in use 
Volume Bit Map for a Disk II diskette is in Block 6 and is 35 bytes in length. 


panel 3 Also See Page 4-5 


SYSTEM GLOBAL PAGE FORMAT 


ADDR CONTENTS ADDR CONTENTS 


BFOO JMP to MLI BF7A-7B Open file 6 
BFO3 JMP to $BFF6 BF7C-7D Open file 7 
BFO6 JMP to Date/Time Address BF7E-7F Open file 8 
(or RTS if no clock) BF80-87 Interrupt address table 
BFO9 JMP to System Error BF80-81 Priority 1 
BFOC JMP to System Death BF82-83 Priority 2 
BFOF System Error number BF84-85 Priority 3 
BF10-2F Device Driver address table BF86-87 Priority 4 
BF10-11 Slot 0 reserved BF88 A register savearea 
BF12-13 Slot 1, Drive 1 BF89 X register savearea 
BF14-15 Slot 2, Drive 1 BFBA Y register savearea 
BF16-17 Slot 3, Drive 1 BF8B S register savearea 
BF18-19 Slot 4, Drive 1 BF8C P register savearea 
BF1A-1B Slot 5, Drive 1 BF8D Bank ID byte (ROM/RAM) 
BF1C-1D Slot 6, Drive 1 BF8E-8F Interrupt return address 
BFIE-1F Slot7, Drive 1 BF90-91 Date 
BF20-21 Slot O reserved BF92-93 Time 
BF22-23 Slot 1, Drive2 BF94 Current File Level 
BF24-25 Slot 2, Drive2 BF95 Backup Bit 
BF26-27 /RAM BF96-97 Currently Unused 
BF28-29 Slot 4, Drive2 BF98 Machine ID byte 
BF2A-2B Slot 5, Drive 2 BF99 Slot ROM bit map 
BF2C-2D Slot 6, Drive 2 BF9A Prefix Flag (0 = no Prefix) 
BF2E-2F Slot 7, Drive2 BF9B MLI active Flag 
BF30 Slot/Drive last device BF9C~9D Last MLI call return 
BF31 Count (-1) active devices address 
BF32-3F List of active devices (ID) | BF9E ML! X register savearea 
BF40-4F Copyright Notice BFOF ML! Y register savearea 
BF50-55 Bank in RAM call IRQ ($FFD8)| BFAO-CF Lang. card entry/exit 
BF56-57 Temporary storage ($FF9B) routines 
BF58-6F Bitmap low 48K of memory BFDO-F3 Interrupt entry/exit 


‘ routines 
Breete ree File buffer address BFF4 _— Storage for byte at $E000 


BF70-71 Open file 1 BFF5 Storage for byte at $0000 
BF72-73 Opentile 2 BFF6-F9 Call System Death (SD1E4) 
BF74-75 Open file 3 BFFC Interpreter minimum 


Version 
BF/76-77 Open file 4 : 
BF78-79 Open tile 5 BFFD Interpreter Version 


number 
BFFE Kernel minimum version 
Kernel version number 


MACHINE IDENTIFICATION BYTE ($BF98) 





00.. 0... TI ..00 .... unused 

01.. 0... Ik ..01 .... 48K 

10.. O... Tle ..10 .... 64K 

11.. 0... Temulation 1100... 128K 

00.. 1... Future expansion .X.. Reserved 

01.. 1... Future expansion ..0. no 80-column card 
10.. 1... Ile .. 1. 80-column card 
11.. 1... Future expansion ...0 no compatible clock 


.... ...1 compatible clock 
panel 4 Also See Pages 8-5 to 8-8 


Bl GLOBAL PAGE FORMAT 


CONTENTS 


CONTENTS 





JMP to WARMDOS 
JMP to command parse 
JMP to user parser 
JMP to error handler 
JMP to error printer 
Error code number 
Output vectors 

Input vectors 

Current output vec 
Current input vec 
Output intercept addr 
Input intercept addr 
STATE intercepts 
Default slot 

Default drive 

A,X,Y savearea 
TRACE active flag 
STATE (0=immediate) 
EXEC active flag 
READ active flag 
WRITE active flag 
PREFIX active flag 
DIR file READ flag 
not used 

STRINGS space count 
Buffered write count 
Command line length 
Previous character 
Open file count 

EXEC file closing flag 
CATALOG line state 
External cmd handler 
Command name tength 


Number of command 
PBITS (permitted) 
FBITS (found) 

A keyword value 

B keyword value 

E keyword value 

L keyword vaiue 

S keyword value 

D keyword value 

F keyword value 

R keyword value 

V keyword value 

@ keyword value 

T keyword value 
PR#/IN# slot value 
Pathname 1 addr 
Pathname 2 addr 
GOSYSTEM MLI interf. 
Last MLI catl number 
Last MLI parmlist addr 
CREATE parmiist 
GET_PREFIX parmlist 
RENAME parmlist 
GET_FILE_INFO parmlist 
ONLINE parmiist 
OPEN parmlist 
SET_NEWLINE parmlist 
READ parmlist 

CLOSE parmlist 
reserved 

JMP to GETBUFR 

JMP to FREEBUFR 
Original HIMEM MSB 





COMMAND NUMBERS: 

00= external 07= EXEC OE=BSAVE 15= APPEND 1C=CATALOG 
O1= IN# 08= LOAD OF= CHAIN 16= CREATE 1D=RESTORE 
02= PR# 09= SAVE 10= CLOSE 17= DELETE 1E= POSITION 
03= CAT OA= OPEN 11= FLUSH = 18= PREFIX 

04= FRE OB= READ 12= NOMON 19= RENAME 

O5= RUN OC= SAVE 13= STORE 1A=UNLOCK 

O6= BRUN OD=BLOAD 14= WRITE ~~ 1B=VERIFY 


PBITS/FBITS BIT ASSIGNMENTS: 


$8000 Prefix needed 
$4000 Slot number only 


$2000 Deferred command 
$1000 File name optional 


$0800 Create file 
$0400 T keyword ok 
$0200 Path 2 expected 
$0100 Path 1 expected 


panel 5 


$0080 AD keyword ok 
$0040 B keyword ok 
$0020 E keyword ok 
$0010 L keyword ok 
$0008 @ keyword ok 
$0004 S or D ok 
$0002 F keyword ok 
$0001 R keyword ok 


Also See Pages 8-2 to 8-6 


MLI CALLS 


JSR SBFOG 
DFB function code 
DW addr of parms 
On return carry flag set if 
error and A reg has return code. 
Also See Page 6-12 


ADDAESS OF 
HANDLER 












RESERVED 





92Fed 


RESERVED 
RESERVED 
RESERVED 


UNIT BITS: 
DSSS0000 


















$566 















UNIT NUMBER 


ADDRESS OF 
DATA BUFFER 


$2293 








+—___ 





BLOCK NUMBER 







* Shaded fields are outputs only or 
do not need initialization. 
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UNIT NUMBER 


ADDRESS OF 
DATA BUFFER 


a 


UNIT BITS: 
DSSS 0000 















BLOCK NUMBER 





















ADDRESS OF 
PATHNAME 





ACCESS 
BITS. 


TYPE 


AUXILIARY 
FILE TYPE. 


STORAGE 
TYPE 


25/96 









CREATION 
GATE 





CREATION 
TIME 


+__ 





ACCESS: DNBOOCOWR 
FILE TYPE: (see next panel) 
AUX_TYPE: TXT=Rec Len 

BIN, BAS, VAR = Address 
STORAGE TYPE: 

$01—Seedling 

$02—Sapling 

$03—Tree 

$0D—Directory 
DATE: YYYYYYYM MMMDDDOD 
TIME: OOOHHHHH 0OOMMMMMM 
PATHNAME Buffer must start with 
one byte length followed by name 
(MSB off) 


Also See Pages 6-15 to 6-25 





ADDRESS OF ADDRESS OF 
PATHNAME bled PATHNAME 


-3C2 RENAM { g/) 
Ze 


ADDAESS OF 
OLD PATHNAME 
ADORESS OF 
NEW PATHNAME 


WED 
lad 


GET_FILE_INFO on Vol Dir returns 
blocks on Volume in AUX_TYPE, 
blocks in use by all files in blocks 
used. 











UNIT BITS: 
DSSS 0000 


6 
OATE OF LAST or 
* UNIT NUMBER 
MODIFICATION 0000 0000 
N 


TIME OF LAST nye ADDRESS OF 
MODIFICATION QATA BUFFER 








Also See Pages 6-26 to 6-38 


FILE TYPES: 





$00 TYPELESS $1B ASP $FD VAR 

$01 BAD $EF PAS $FE REL 

$04 TXT $FO Added Command $FF SYS 

$06 BIN $F1-$F8 User Defined 

$OF DIR $FA Integer BASIC pgm All others are 
$19 ADB $FB Integer BASIC vars SOS only or are 
$1A AWP $FC BAS reserved. 


Also See Pages 4-10 to 4-30 


REFERENCE 
NUMBER 


REFERENCE 
NUMBER 










































REFERENCE 
NUMBER 


REFERENCE 
NUMBER 











REFERENCE 
NUMBER 


$00 DISABLE ° 

SFF MATCH 

$7F IGNORE 4 
MSB 





NEW FILE POSITION 






Also See Pages 6-39 to 6-54 









REFERENCE 
NUMBER 







REFERENCE 
NUMBER 












NEW EOF 
POSITION 






NEW ADDRESS OF 
FILE BUFFER, 


92t93ted 









REFERENCE 
NUMBER 





REFERENCE 
NUMBER, 


MLI ERROR CODES 


12regied 





$00 No error $48 Disk full 
$01 Invalid MLI function $49 Vol DIR full 
$04 Invalid parameter count $4A Incompatible ProDOS version 
$25 Interrupt table full $4B Unsupported storage type 
$27 |/O error $4C End of file 
$28 No device connected $4D Position past EOF 
$2B Write protected $4E Access error 
$2E Volume switched $50 File already open 
$40 Invalid pathname syntax $51 File count bad 
$42 Too many files open $52 Nota ProDOS disk 
$43 Invalid REF NUM $53 Bad parameter 
$44 Nonexistent path $55 VCB overflow 
$45 Volume not mounted $56 Bad buffer addr. 
$46 File not found $57 Duplicate volume 
$47 Duplicate file name $5A Bad vol. bit map 
Also See Pages 6-54 to 6-61 
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